Developer CD Series 1996 April: Mac OS SDK/Dev.CD Apr 96 SDK/Dev.CD Apr 96 SDK1.toast/Development Kits (Disc 1)/OpenDoc/Sample Code/Sample Editors⁄Viewers/Cappuccino/Source/Cappuccino.cpp

Text File | 1995-12-11 | 131.4 KB | 4,141 lines | [TEXT/MPS ]

/*------------------------------------------------------------------------------

    File:            Cappuccino.cpp

    Written by:        Steve Smith & Troy Gaul

    Copyright:        © 1995 by Apple Computer, Inc., all rights reserved.

    Description:    Cappuccino demonstrates the most basic functions and
                    responsibilities of an OpenDoc™ leaf part.


    Demonstrates:    The following recipes were used in implementing
                    Cappuccino:
                     1. Open
                     2. Adding A Display Frame
                     3. Adding A Facet
                     4. Part Drawing
                     5. Refcounting Geometry
                     6. ViewTypes & Presentations
                     7. Display Frame 'ternalization
                     8. Part Init & Externalization
                     9. Part Init & partWrapper
                    10. Part Storage Model
                    11. Persistent Reference
                    12. RefCounting
                    13. Storage Unit
                    14. Activation
                    15. Basic Event Handling
                    16. Menus
                    17. Windows & Dialogs
                    18. Exception Handling
                    19. Memory Manager
                    20. Using Resources
                    21. Lazy Frame Internalization
                    22. Multiple Kind Support

                    Also, recipes for the following features are implemented:

                        Scripting
                        Undo
                        Promises
                        Printing
                        Clipboard support
                        Drag and drop
                        Settings extension
                        Translation


    Notes:            • For methods where it is necessary to call the parent class
                    implementation, the calls are made from the SOM class. See
                    som_Cappuccino.cpp and the Class Reference to know whether
                    you need to call the parent class from any method.

------------------------------------------------------------------------------*/

// -- Compiler/Preprocessor Switches --

#ifndef _COMPILERDEFS_
#include "CompDefs.h"
#endif

// -- OpenDoc Utilities --

#ifndef _EXCEPT_
// Exceptions define several important macros (eg. CHECKENV)
// which are used in the SOM method dispatch glue. If Except.h
// is not included early enough, exceptions may not be thrown
// correctly when returning from a SOM method with the "ev" parameter set.
#include <Except.h>
#endif

// -- Cappuccino Includes --

#ifndef _CAPPUCCINO_
#include "Cappuccino.h"
#endif

#ifndef _CAPPUCCINOACTION_
#include "CappuccinoAction.h"
#endif

#ifndef _CAPPUCCINOCONTENT_
#include "CappuccinoContent.h"
#endif

#ifndef _CAPPUCCINODEF_
#include "CappuccinoDef.h"
#endif

#ifndef _CAPPUCCINOGLOBALS_
#include "CappuccinoGlobals.h"
#endif

#ifndef _CAPPUCCINOPROMISE_
#include "CappuccinoPromise.h"
#endif

#ifndef SOM_CappuccinoSI_xh
#include "som_CappuccinoSI.xh"
#endif

#ifndef _CAPPUCCINOUTILS_
#include "CappuccinoUtils.h"
#endif

#ifndef SOM_som_CappuccinoSettingsExtension_xh
#include "som_CappuccinoSettingsExt.xh"
#endif

#ifndef _SAMPLECOLLECTIONS_
#include "SampleCollections.h"
#endif

#ifndef _PRINTER_
#include "Printer.h"
#endif

#ifndef _TEMPFOCUS_
#include "TempFocus.h"
#endif

// -- OpenDoc Includes --

#ifndef _ODTYPES_
#include <ODTypes.h>
#endif

#ifndef SOM_ODArbitrator_xh
#include <Arbitrat.xh>
#endif

#ifndef SOM_ODCanvas_xh
#include <Canvas.xh>
#endif

#ifndef SOM_Module_OpenDoc_Commands_defined
#include <CmdDefs.xh>
#endif

#ifndef SOM_ODDraft_xh
#include <Draft.xh>
#endif

#ifndef SOM_ODFacet_xh
#include <Facet.xh>
#endif

#ifndef SOM_Module_OpenDoc_Foci_defined
#include <Foci.xh>
#endif

#ifndef SOM_ODFocusSet_xh
#include <FocusSet.xh>
#endif

#ifndef SOM_ODFrame_xh
#include <Frame.xh>
#endif

#ifndef SOM_ODFrameFacetIterator_xh
#include <FrFaItr.xh>
#endif

#ifndef SOM_ODMenuBar_xh
#include <MenuBar.xh>
#endif

#ifndef SOM_ODSession_xh
#include <ODSessn.xh>
#endif

#ifndef SOM_ODPart_xh
#include <Part.xh>
#endif

#ifndef SOM_ODShape_xh
#include <Shape.xh>
#endif

#ifndef SOM_Module_OpenDoc_StdDefs_defined
#include <StdDefs.xh>
#endif

#ifndef SOM_Module_OpenDoc_StandardExtensions_defined
#include <StdExts.xh>
#endif

#ifndef SOM_Module_OpenDoc_StdProps_defined
#include <StdProps.xh>
#endif

#ifndef SOM_Module_OpenDoc_StdTypes_defined
#include <StdTypes.xh>
#endif

#ifndef SOM_ODStorageUnit_xh
#include <StorageU.xh>
#endif

#ifndef SOM_ODStorageUnitView_xh
#include <SUView.xh>
#endif

#ifndef SOM_ODTranslation_xh
#include <Translt.xh>
#endif

#ifndef SOM_ODTransform_xh
#include <Trnsform.xh>
#endif

#ifndef SOM_ODWindow_xh
#include <Window.xh>
#endif

#ifndef SOM_ODWindowState_xh
#include <WinStat.xh>
#endif

// -- OpenDoc Utilities --

#ifndef _BNDNSUTL_
#include <BndNSUtl.h>
#endif

#ifndef _DLOGUTIL_
#include <DlogUtil.h>
#endif

#ifndef _FOCUSLIB_
#include <FocusLib.h>
#endif

#ifndef _ISOSTR_
#include <ISOStr.h>
#endif

#ifndef _ITEXT_
#include <IText.h>
#endif

#ifndef _ODDEBUG_
#include <ODDebug.h>
#endif

#ifndef _ODMEMORY_
#include <ODMemory.h>
#endif

#ifndef _ODUTILS_
#include <ODUtils.h>
#endif

#ifndef _STDTYPIO_
#include <StdTypIO.h>
#endif

#ifndef _STORUTIL_
#include <StorUtil.h>
#endif

#ifndef _TEMPITER_
#include <TempIter.h>
#endif

#ifndef _TEMPOBJ_
#include <TempObj.h>
#endif

#ifndef _USERSRCM_
#include <UseRsrcM.h>
#endif

#ifndef _WINUTILS_
#include <WinUtils.h>
#endif

// -- Macintosh Includes --

#ifndef __DIALOGS__
#include <Dialogs.h>
#endif

#ifndef __ERRORS__
#include <Errors.h>
#endif

#ifndef __GXMATH__
#include <GXMath.h>
#endif

#ifndef __ICONS__
#include <Icons.h>
#endif

#ifndef __RESOURCES__
#include <Resources.h>
#endif

#ifndef __TOOLUTILS__
#include <ToolUtils.h>
#endif

#ifndef __QUICKDRAW__
#include <Quickdraw.h>
#endif

#ifndef __SPEECH__
#include <Speech.h>
#endif

#pragma segment Cappuccino

//==============================================================================
// Cappuccino
//==============================================================================

//==============================================================================
#pragma mark    • Construction and Destruction •
//==============================================================================

//------------------------------------------------------------------------------
// Method:        CreatePartObject                                    [static]
// Origin:        Cappuccino
//
// Description:    This static method is called by the SOM part object when it
//                needs to create a new instance of this part.  This is done so
//                that this function can be removed from here and implemented by
//                a subclass to create an instance of the correct class.
//------------------------------------------------------------------------------

Cappuccino* Cappuccino::CreatePartObject()
{
    return new Cappuccino;
}

//------------------------------------------------------------------------------
// Method:        Constructor
// Origin:        Cappuccino
//
// Description:    This is the C++ class constructor.
//
// Warnings:    You are not allowed to throw an exception from this method.
//------------------------------------------------------------------------------

Cappuccino::Cappuccino()
{
    SOM_Trace("Cappuccino","Constructor");

    fDisplayFrames            = kODNULL;
    fSelf                    = kODNULL;

    fDirty                    = kODFalse;
    fReadOnlyStorage        = kODFalse;

    fSettingsExtension        = kODNULL;
    fSemanticInterface        = kODNULL;

    fPrinter                = kODNULL;
    fHighlightedDragFacet    = kODNULL;

    fContent                = kODNULL;
    fPreferredKind            = kODNULL;

    fSettings                = kODNULL;
}

//------------------------------------------------------------------------------
// Method:        Destructor
// Origin:        Cappuccino
//
// Description:    This is the C++ class destructor.
//
// Warnings:    You are not allowed to throw an exception from this method.
//------------------------------------------------------------------------------

Cappuccino::~Cappuccino()
{
    SOM_Trace("Cappuccino","Destructor");
}

//==============================================================================
#pragma mark    • Initialization •
//==============================================================================

//------------------------------------------------------------------------------
// Method:        InitPart
// Origin:        ODPart
//
// Description:    This method is called when a new instance of this part is being
//                created. The part should prepare itself to run.
//
// Parent:        The part's parent class was called before this method was
//                dispatched to (see som_Cappuccino.cpp).
//
// Warning:        It is not appropriate to require user interaction while
//                stationery is being created. Do not present the user with error
//                dialogs or splash screens from this method.
//------------------------------------------------------------------------------

void Cappuccino::InitPart( Environment*        ev,
                           ODStorageUnit*    storageUnit,
                           ODPart*            partWrapper )
{
    SOM_Trace("Cappuccino","InitPart");

    TRY
        // To allow editor swapping (translation) at runtime, OpenDoc requires
        // that we pass in a "reference" to ourselves when interacting with the
        // API (eg. WindowState::RegisterWindow(), Dispatcher::RegisterIdle, etc).
        // The "partWrapper" passed to us here and in InitPartFromStorage is the
        // "reference" OpenDoc is asking us to use.
        fSelf = partWrapper;

        // We are being created, either as part of generating stationery or
        // by some editor instantiating the part, so the destination storage
        // must be writeable.
        fReadOnlyStorage = kODFalse;

        // Create the printer object.
        fPrinter = CPrinter::New(ev, storageUnit);

        // Set up the default preferred kind.
        fPreferredKind = kCappuccinoKind;

        // Call the common initialization code to get set up.
        this->Initialize(ev);

        // Since we have just been created, our state/content info has
        // never been written out, so setting our "dirty" flag will
        // give us a chance to do that.
        this->SetDirty(ev);

    CATCH_ALL
        // Clean up will occur in the destructor which will be called
        // shortly after we return the error.
        RERAISE;
    ENDTRY
}

//------------------------------------------------------------------------------
// Method:        InitPartFromStorage
// Origin:        ODPart
//
// Description:    This method is called when a document/stationery is being opened
//                or when the part is internalized by its containing part. The
//                part should merely read in the saved state/content and
//                initialize itself. The part must not alter its storage unit;
//                otherwise, the "Save" menu item becomes enabled without the user
//                actually having made a change to the document.
//
// Parent:        The part's parent class was called before this method was
//                dispatched to (see som_Cappuccino.cpp).
//------------------------------------------------------------------------------

void Cappuccino::InitPartFromStorage( Environment*        ev,
                                      ODStorageUnit*    storageUnit,
                                      ODPart*            partWrapper )
{
    SOM_Trace("Cappuccino","InitPartFromStorage");

    TRY
        // To allow editor swapping (translation) at runtime, OpenDoc requires
        // that we pass in a "reference" to ourselves when interacting with the
        // API (eg. WindowState::RegisterWindow(), Dispatcher::RegisterIdle, etc).
        // The "partWrapper" passed to us here and in InitPart is the
        // "reference" OpenDoc is asking us to use.
        fSelf = partWrapper;

        // Are we being opened from a read-only draft? If so, we cannot
        // write anything back out to our storage unit.
        fReadOnlyStorage = ( ODGetDraft(ev, storageUnit)->
                                GetPermissions(ev) < kODDPSharedWrite );

        // Create the printer object.
        fPrinter = CPrinter::New(ev, storageUnit);

        // Call the common initialization code to get set up.
        this->Initialize(ev);

        // Read in the state the part was in when it was last Externalized.
        // This allows the part to present the same "environment" the user
        // had the part set up in the last time it was edited.
        this->InternalizeStateInfo(ev, storageUnit);

        // Read in the contents for your part editor.
        this->InternalizeContent(ev, storageUnit);

    CATCH_ALL
        // Clean up will occur in the destructor which will be called
        // shortly after we return the error.
        RERAISE;
    ENDTRY
}

//------------------------------------------------------------------------------
// Method:        Initialize
// Origin:        Cappuccino
//
// Description:    This method is called during the initialization of the part. The
//                method is used to initialize all fields of the part and to
//                convert ISO types to tokens for faster comparisons throughout
//                the code.
//
//                If an exception is thrown in this method, it wil be propogated
//                back to OpenDoc which will call our ReleaseAll() method and the
//                class destructor. All memory allocated here will be cleaned up
//                in the ReleaseAll() method.
//------------------------------------------------------------------------------

void Cappuccino::Initialize( Environment*    ev )
{
    SOM_Trace("Cappuccino","Initialize");

    // Store the session in a member variable. This is merely for convenience.
    fSession = ODGetSession(ev, fSelf);

    // Create our content object (we should have one at all times).
    fContent = new CCappuccinoContent(this);
    fContent->InitCappuccinoContent(ev);

    // Create our settings object to track part settings.
    fSettings = new CSettings(this);
    fSettings->InitSettings(ev);

    // Create a list to keep track of the frames we are being
    // displayed in. Used for part maintenance (ie. Purging memory).
    fDisplayFrames = new CList;

    // First check to see if the library's global variables have
    // been initialized (meaning another part instantiation is already
    // running).

    if ( gGlobalsUsageCount == 0 )
    {
        // Create our globals space. We store the globals in a struct so
        // that we can put them in temp mem. Otherwise, CFM loads the globals
        // with the data fragment of a CFM library in the application heap.
        gGlobals = new CappuccinoGlobals;

        // We will be using the following foci (shared resources) in this
        // part. For convenience, we tokenize the values here and store
        // them for equivalence tests in the activation methods.
        gGlobals->fSelectionFocus    = fSession->Tokenize(ev, kODSelectionFocus);
        gGlobals->fMenuFocus        = fSession->Tokenize(ev, kODMenuFocus);
        gGlobals->fModalFocus        = fSession->Tokenize(ev, kODModalFocus);

        // Also for convenience, we tokenize our part's main presentation
        // and the standard view types.
        gGlobals->fMainPresentation = fSession->Tokenize(ev, kMainPresentation);

        gGlobals->fFrameView     = fSession->Tokenize(ev, kODViewAsFrame);
        gGlobals->fLargeIconView = fSession->Tokenize(ev, kODViewAsLargeIcon);
        gGlobals->fSmallIconView = fSession->Tokenize(ev, kODViewAsSmallIcon);
        gGlobals->fThumbnailView = fSession->Tokenize(ev, kODViewAsThumbnail);

        // This part supports TEXT data and files, so we must get the value types
        // OpenDoc associates with each. We do this through the Translation object.
        gGlobals->fTextDataValueType = fSession->GetTranslation(ev)->
                        GetISOTypeFromPlatformType(ev, 'TEXT', kODPlatformDataType);

        // Value type for file information
        gGlobals->fAppleHFSFlavorValueType = fSession->GetTranslation(ev)->
                        GetISOTypeFromPlatformType(ev, 'hfs ', kODPlatformDataType);

        // Lastly, we will package the menu and selection focus
        // so that we can request the "set" at activation time.
        gGlobals->fUIFocusSet = fSession->GetArbitrator(ev)->CreateFocusSet(ev);
        gGlobals->fUIFocusSet->Add(ev, gGlobals->fMenuFocus);
        gGlobals->fUIFocusSet->Add(ev, gGlobals->fSelectionFocus);

        // If we wanted to support keyboard input (such as supporting F1 - F4
        // for undo, cut, copy, paste -- which aren't supported automatically
        // by OpenDoc 1.0 -- or adding key input capability), we would need
        // to add a key focus for this, and we'd add it to our UI focus set.

        // Add our resource-based menus and register all the editor specific
        // command numbers.
        this->BuildMenuBar(ev);

        // Determine what Script/Language the part is localized for.
        // This is important/necessary for creating OpenDoc's text objects.
        GetEditorScriptLanguage(ev, &gGlobals->fEditorsScript, &gGlobals->fEditorsLanguage);

        // Create an object to track promises on the clipboard and drag & drop.
        gGlobals->fClipboardPromises = new CPromiseSet;
        gGlobals->fDragPromises = new CPromiseSet;

        // The first client of the global variables is running.
        gGlobalsUsageCount = 1;
    }
    else
    // If the globals have been initialized, we just bump the "usage" count so
    // that we know how many part instances are using them.
    {
        gGlobalsUsageCount++;
    }
}

//==============================================================================
#pragma mark    • Storage •
//==============================================================================

//------------------------------------------------------------------------------
// Method:        Release
// Origin:        ODPart
//
// Description:    This method is called each time an object releases a reference
//                to the part. If the refcount falls to 0, the part should
//                release the fSelf part reference.
//
// Parent:        The part's parent class was called before this method was
//                dispatched to (see som_Cappuccino.cpp).
//
// Warning:        If the part releases any other object when the refcount falls to
//                zero, it will need to override the Acquire method so
//                that the object can be referenced again if the parts refcount
//                should be incremented before it is deleted.
//------------------------------------------------------------------------------

void Cappuccino::Release( Environment* ev )
{
    SOM_Trace("Cappuccino","Release");

    if ( fSelf->GetRefCount(ev) == 0 )
        ODGetDraft(ev, fSelf)->ReleasePart(ev, fSelf);
}

//------------------------------------------------------------------------------
// Method:        ReleaseAll
// Origin:        ODPart
//
// Description:    This method is called just prior to the part being deleted by
//                the Draft. The part must release all references to all
//                refcounted objects it has stored internally; not doing so, will
//                cause an "invalid ref count" exception/error at some later time.
//
// Parent:        The part's parent class will be called after this method
//                returns (see som_Cappuccino.cpp).
//------------------------------------------------------------------------------

void Cappuccino::ReleaseAll( Environment* ev )
{
    SOM_Trace("Cappuccino","ReleaseAll");

    TRY
        // Release the content object.
        if ( fContent )
        {
            fContent->Release();
            fContent = kODNULL;
        }

        // Release the settings object.
        if ( fSettings )
        {
            fSettings->Release();
            fSettings = kODNULL;
        }

        // Delete the printer object.
        ODDeleteObject(fPrinter);

        // Release our extensions.  Note: we can't use ODReleaseObject or
        // ODFinalReleaseObject here because they null out the field before the
        // call to Release, but we need the field intact when ReleaseExtension is
        // called back upon the last reference being released.
        ODRelease(ev, fSettingsExtension);
        ODRelease(ev, fSemanticInterface);

        // If the last part instance using the globals is released,
        // we need to clean up and delete the globals.

        if ( --gGlobalsUsageCount == 0 )
        {
            // But first, we need to delete the objects we created
            // and stored in the globals struct.
            ODDeleteObject(gGlobals->fUIFocusSet);

            // Dispose the memory used by our ISO strings.
            ODDisposePtr(gGlobals->fTextDataValueType);
            ODDisposePtr(gGlobals->fAppleHFSFlavorValueType);

            // We need to remove our menus from the menubar and dispose of
            // them to free up their memory.
            for (ODSShort index = 0; index < kNumMenus; index++)
            {
                ODSShort id = kBaseMenuID + index;

                MenuHandle menu = gGlobals->fMenuBar->GetMenu(ev, id);
                gGlobals->fMenuBar->RemoveMenu(ev, id);
                if ( menu != kODNULL )
                {
                    CUsingLibraryResources res;
                    ReleaseResource((Handle) menu);
                }
            }

            // Release the menubar.
            ODReleaseObject(ev, gGlobals->fMenuBar);

            // Dispose the thumbnail picture.
            if ( gGlobals->fThumbnail != kODNULL )
                ReleaseResource(gGlobals->fThumbnail);

            // Delete the object that tracks promises on the clipboard.
            ODDeleteObject(gGlobals->fClipboardPromises);
            ODDeleteObject(gGlobals->fDragPromises);

            // Now, clean up the globals struct.
            ODDeleteObject(gGlobals);

#if ODDebug
            // This is a debugging routine that checks to see if all of the ref-
            // counted objects of ours have been released before this point.
            CheckRefCountedObjects();
#endif
        }

        // Remove and release our display frames.
        if ( fDisplayFrames )
        {
            CListIterator fiter(fDisplayFrames);
            for ( CFrameProxy* proxy = (CFrameProxy*) fiter.First();
                    fiter.IsNotComplete(); proxy = (CFrameProxy*) fiter.Next() )
            {
                // Delete the proxy object and its contents. The frame's
                // refcount will be decremented in the proxy destructor.
                fiter.RemoveCurrent();
                delete proxy;
            }

            // Delete the display frame collection.
            ODDeleteObject(fDisplayFrames);
        }

    CATCH_ALL
        // If something goes wrong while we are cleaning up, we must
        // let the Draft now because there may be some refcounted objects
        // which did not get released. Not to mention, possible memory
        // leaks.
        RERAISE;
    ENDTRY
}

//------------------------------------------------------------------------------
// Method:        Purge
// Origin:        ODPart
//
// Description:    This method is called when the OpenDoc requires more memory for
//                allocating objects and just before a part is deleted. The part
//                should free up as much memory as it can.
//
//                The part determines which views are being "used" in its display
//                frames. The resources for the unused view types are then purged.
//------------------------------------------------------------------------------

ODSize Cappuccino::Purge( Environment*    ev,
                          ODSize        size )
{
    SOM_Trace("Cappuccino","Purge");

    // Purge is called during the creation of stationery. However,
    // we have not created our internal display frames list, so
    // trying to iterate over it would be fatal.
    if ( fDisplayFrames == kODNULL ) return 0;

    ODSize         bytesFreed        = 0;
    ODBoolean    usingThumbnail  = kODFalse;

    // Iterate over the frames we are displayed through and determine which
    // view types are currently in use.

    CListIterator fiter(fDisplayFrames);
    for ( CFrameProxy* proxy = (CFrameProxy*) fiter.First();
            fiter.IsNotComplete(); proxy = (CFrameProxy*) fiter.Next() )
    {
        // If the display frame is real (has been "connected" or was "added")
        // get its view type; otherwise, ignore it.
        if ( proxy->FrameIsLoaded(ev) )
        {
            ODTypeToken    frameView = proxy->GetFrame(ev)->GetViewType(ev);

            if ( frameView == gGlobals->fThumbnailView )
                usingThumbnail = kODTrue;

            // Release the frame reference, but don't get rid of the
            // proxy object because we're not done with the frame. If
            // all parts release their references the frame will be
            // purged from memory.
            proxy->Purge(ev);
        }
    }

    // Based on the usage of the supported view types, free up as much
    // memory as possible.

    if ( !usingThumbnail && (gGlobals->fThumbnail != kODNULL) )
    {
        bytesFreed += (ODSize) ODGetHandleSize(gGlobals->fThumbnail);
        ReleaseResource(gGlobals->fThumbnail);
        gGlobals->fThumbnail = kODNULL;
    }

    return bytesFreed;
}

//------------------------------------------------------------------------------
// Method:        InternalizeStateInfo
// Origin:        Cappuccino
//
// Description:    This method is used to read in "state" information for the part.
//                This is information related to the workings of the part editor,
//                not the content.
//
//                The part writes out a list of weak references to its display
//                frames. This allows the part to reuse the same display frames
//                each time the document is opened. Those references are read
//                back in and validated here.
//
// Note:        The function StorageUnitGetValue simplifies the use of
//                ODByteArrary, which is required the StorageUnit interface. Look
//                in StorUtil.h/cpp for an example of using the ODByteArray struct.
//------------------------------------------------------------------------------

void Cappuccino::InternalizeStateInfo( Environment*        ev,
                                       ODStorageUnit*    storageUnit )
{
    SOM_Trace("Cappuccino","InternalizeStateInfo");

    // Internalize annotation properties.
    WASSERT(fSettings != kODNULL);
    fSettings->Release();
    fSettings = kODNULL;

    fSettings = new CSettings(this);
    fSettings->InitSettings(ev, storageUnit);

    // Internalize the part's display frame list.
    if ( ODSUExistsThenFocus(ev, storageUnit, kODPropDisplayFrames, kODWeakStorageUnitRefs) )
    {
        ODULong size = storageUnit->GetSize(ev);
        storageUnit->SetOffset(ev, 0);

        for ( ODULong offset = 0; offset < size; offset += kODStorageUnitRefSize )
        {
            TRY
                // We lazily internalize our display frames, meaning we don't "get"
                // the frame until we absolutely need it. This reduces the time
                // to internalize the part and the amount of memory needed.

                // Convert the reference into a runtime id.
                ODID frameID = ODGetWeakSURefProp(ev, storageUnit, kODNULL, kODNULL);
                if ( frameID != kODNULLID )
                {
                    // Create a proxy class to support the lazy internalization.
                    CFrameProxy* proxy = new CFrameProxy;
                    proxy->InitFrameProxy(frameID, ODGetDraft(ev, storageUnit));

                    // Add the proxy to the display frame collection.
                    fDisplayFrames->Add(proxy);
                }
            CATCH_ALL
                // consume exception
            ENDTRY
        }
    }
}

//------------------------------------------------------------------------------
// Method:        InternalizeContent
// Origin:        Cappuccino
//
// Description:    This method is called during initialization of the part from an
//                existing document. The content of the part should be read in.
//
//                The part has no intrinsic content, so the part does nothing.
//                The method is here for completeness.
//------------------------------------------------------------------------------

void Cappuccino::InternalizeContent( Environment*        ev,
                                     ODStorageUnit*        storageUnit )
{
    SOM_Trace("Cappuccino","InternalizeContent");

    WASSERT(fContent != kODNULL);
    fContent->Release();
    fContent = kODNULL;

    fContent = new CCappuccinoContent(this);
    fContent->InitCappuccinoContent(ev, storageUnit);

    // If we don't have a preferred kind yet, use the kind that was found,
    // if any.  Otherwise, use our default kind.
    if ( fPreferredKind == kODNULL )
    {
        // This is actually a little wasteful, as this kind was just determined
        // by InitCappuccinoContent, but that routine doesn't return it to us,
        // so we have to calculate it again.  This is one of several optimization
        // opportunities.
        ODValueType kindToUse = CCappuccinoContent::GetKindToInternalize(ev, storageUnit);
        fPreferredKind = (kindToUse != kODNULL) ? kindToUse : kCappuccinoKind;
    }
}

//------------------------------------------------------------------------------
// Method:        CloneInto
// Origin:        ODPart
//
// Description:    This method is called during cloning, typically during data
//                interchange operations (eg. Cut/Paste). The part should
//                write out its current state and content.
//
// Parent:        The part's parent class was called before this method was
//                dispatched to (see som_Cappuccino.cpp).
//------------------------------------------------------------------------------

void Cappuccino::CloneInto( Environment*        ev,
                            ODDraftKey            key,
                            ODStorageUnit*        destinationSU,
                            ODFrame*            initiatingFrame )
{
    SOM_Trace("Cappuccino","CloneInto");

    // We must first verify that we've never written to this storage unit.
    // If we have, we should do nothing, otherwise we need to write out
    // the current state of the part content.

    // To do this, we call CCappuccinoContent::HasSupportedKind, which will
    // return kODFalse if there are no recognized types in the storage unit.

    if ( !fContent->HasSupportedKind(ev, destinationSU) )
    {
        // Add the properties we need to successfully externalize
        // ourselves into the destination storage unit.
        this->CheckAndAddProperties(ev, destinationSU);

        // Write out the part's state information.
        this->ExternalizeStateInfo(ev, destinationSU, key, initiatingFrame);

        // Write out the part's content.
        this->ExternalizeContent(ev, destinationSU, key, initiatingFrame);
    }
}

//------------------------------------------------------------------------------
// Method:        Externalize
// Origin:        ODPart
//
// Description:    This method is called when the user saves the document. The part
//                should write out its state and content if changes have occurred
//                and if our storage is writeable.
//
// Parent:        The part's parent class was called before this method was
//                dispatched to (see som_Cappuccino.cpp).
//------------------------------------------------------------------------------

void Cappuccino::Externalize( Environment* ev )
{
    SOM_Trace("Cappuccino","Externalize");

    TRY
        if ( fDirty && !fReadOnlyStorage )
        {
            // Get our storage unit.
            ODStorageUnit* storageUnit = fSelf->GetStorageUnit(ev);

            // Verify that the storage unit has the appropriate properties
            // and values to allow us to run. If not, add them.
            this->CheckAndAddProperties(ev, storageUnit);

            // Verify that there are no "bogus" values in the Content
            // property.
            this->CleanseContentProperty(ev, storageUnit);

            // Write out the part's state information.
            this->ExternalizeStateInfo(ev, storageUnit, kODNULLKey, kODNULL);

            // Write out the part's content.
            this->ExternalizeContent(ev, storageUnit, kODNULLKey, kODNULL);

            // Flag our part as no longer being dirty.
            fDirty = kODFalse;
        }

        // PRINTING: Externalize the page setup info. It might be dirty even
        // if fDirty is false, so don't put this in the if block above.
        if ( !fReadOnlyStorage && fPrinter )
        {
            TRY
                fPrinter->Externalize(ev);
            CATCH_ALL
                WARN("Err %d externalizing page setup", ErrorCode());
            ENDTRY
        }
    CATCH_ALL
        // Alert the user of the problem.
        this->DoDialogBox(ev, kODNULL, kErrorBoxID, kErrExternalizeFailed);
        // Change the exception value, so the DocShell doesn't display an
        // error dialog.
        SetErrorCode(kODErrAlreadyNotified);
        // Alert the caller.
        RERAISE;
    ENDTRY
}

//------------------------------------------------------------------------------
// Method:        ExternalizeKinds
// Origin:        ODPart
//
// Description:    This method is called when the user wants to save the document
//                with multiple representations of the data. This is especially
//                useful for increasing the portability of documents
//                cross-platform.
//
//                A part should verify each kind is valid, that it exists in
//                the content property in the correct order, and write the data.
//
// Note:        For parts which support only on kind, the code can simplified.
//                In this case, it is not necessary to iterate over the kindset
//                because you must, at least, write your preferred kind. The code
//                is shown this way to better illustrate the recipe; it is not
//                wrong, it just does more than it needs to.
//------------------------------------------------------------------------------

void Cappuccino::ExternalizeKinds( Environment*        ev,
                                   ODTypeList*        kindset )
{
    WASSERT(fContent != kODNULL);

    if ( !fReadOnlyStorage )
    {
        ODBoolean preferredKindWritten = kODFalse;

        // Get our storage unit.
        ODStorageUnit* storageUnit = fSelf->GetStorageUnit(ev);

        // Verify that the storage unit has the appropriate properties
        // and values to allow us to run. If not, add them.
        this->CheckAndAddProperties(ev, storageUnit);

        // Verify that there are no "bogus" values in the Content
        // property.
        this->CleanseContentProperty(ev, storageUnit);

        // Iterate over the kindset and write out the content types
        // that we support.
        TempODTypeListIterator iter(ev, kindset);
        for ( ODType kind = iter.First(); iter.IsNotComplete(); kind = iter.Next() )
        {
            // Check to see if this is a kind we support. If so, write it.
            if ( fContent->IsKindSupported(ev, kind) )
            {
                // Write out the part's content.
                fContent->ExternalizeOneKind(ev, storageUnit, kODNULLKey, kind);

                // This is our preferrend kind so we don't need to write it again.
                // Part editors with more than one kind need to test each kind
                // against the preferred kind to make sure it's been written.
                if ( ODISOStrEqual(kind, fPreferredKind) )
                    preferredKindWritten = kODTrue;
            }
        }

        // Write out the part's state information.
        this->ExternalizeStateInfo(ev, storageUnit, kODNULLKey, kODNULL);

        // Even if the kind set contains no types we support, we must at least
        // write out our current "preferred" kind.
        if ( preferredKindWritten == kODFalse )
        {
            // Write out the part's preferred content kind.
            fContent->ExternalizeOneKind(ev, storageUnit, kODNULLKey, fPreferredKind);
        }
    }
}

//------------------------------------------------------------------------------
// Method:        ChangeKind
// Origin:        ODPart
//
// Description:    This method is called when the changes the part's primary kind
//                and/or when the part editor is switched via the Info dialog.
//
//                The editor should record the new "preferred" kind and change the
//                UI, if necessary, to allow editing of that kind. Don't write the
//                properties/values/data until the Externalize is called.
//------------------------------------------------------------------------------

void Cappuccino::ChangeKind( Environment*    ev,
                             ODType            kind )
{
    if ( fContent->IsKindSupported(ev, kind) )
    {
        if ( !ODISOStrEqual(kind, fPreferredKind) )
        {
            fPreferredKind = fContent->RecoverKindPtr(ev, kind);

            // Get our storage unit.
            ODStorageUnit* storageUnit = fSelf->GetStorageUnit(ev);

            // Write out the users preferred kind.
            SetPreferredKind(ev, storageUnit, fPreferredKind);

            // Changing our kind dirties our content.
            this->SetDirty(ev);

            // Immediately externalize ourselves in the "new" format.
            this->Externalize(ev);
        }
    }
    else
    {
        THROW(kODErrInvalidValueType);
    }
}

//------------------------------------------------------------------------------
// Method:        ExternalizeStateInfo
// Origin:        Cappuccino
//
// Description:    This method is called during externalization of the part. The
//                current "state" of the part should be written out. This "state"
//                information may be lost during Data Interchange operations, so
//                the part needs to recover gracefully if information is missing
//                or incomplete.
//
// Note:        The function StorageUnitSetValue is a macro which simplifies
//                the use of ODByteArrary, which is required by the StorageUnit
//                interface. Look in StorUtil.h/cpp for an example of using the
//                ODByteArray struct.
//------------------------------------------------------------------------------

void Cappuccino::ExternalizeStateInfo( Environment*        ev,
                                       ODStorageUnit*    storageUnit,
                                       ODDraftKey        key,
                                       ODFrame*            scopeFrame )
{
    SOM_Trace("Cappuccino","ExternalizeStateInfo");

    // Externalize the font and size into annotation properties.
    WASSERT(fSettings != kODNULL);
    fSettings->Externalize(ev, storageUnit);

    // Externalize the page setup info.
    // Note: This is also done in the Externalize method; it's repeated here so
    // it will happen even on a clone operation.
    if ( fPrinter )
    {
        TRY
            fPrinter->Externalize(ev, storageUnit);
        CATCH_ALL
            WARN("Err %d externalizing page setup", ErrorCode());
        ENDTRY
    }

    // Set up the preferred kind property with our preferred kind.
    SetPreferredKind(ev, storageUnit, fPreferredKind);

    // Externalize the part's display frame list.
    storageUnit->Focus(ev, kODPropDisplayFrames, kODPosUndefined,
                       kODWeakStorageUnitRefs, 0, kODPosUndefined);

    // Persistent object references are stored in a side table, rather than
    // in the property/value stream. Thus, deleting the contents of a value
    // will not "delete" the references previously written to that value. To
    // completely "delete" all references written to the value, we must
    // remove the value and add it back.
    storageUnit->Remove(ev);
    storageUnit->AddValue(ev, kODWeakStorageUnitRefs);

    ODID        scopeFrameID = ( scopeFrame ? scopeFrame->GetID(ev) : kODNULLID );
    ODDraft*    fromDraft = ODGetDraft(ev, fSelf);

    CListIterator fiter(fDisplayFrames);
    for ( CFrameProxy* proxy = (CFrameProxy*) fiter.First();
            fiter.IsNotComplete(); proxy = (CFrameProxy*) fiter.Next() )
    {
        // Get the ID of the frame we are going to weakly reference.
        ODID frameID = proxy->GetID();

        // If a draft key exists, then we are being cloned to another draft.
        // We must "weak" clone our display frame and reference the cloned
        // frame. The part re-uses the frameID variable so there aren't two
        // different GetWeakStorageUnitRef calls.
        if ( key )
            frameID = fromDraft->WeakClone(ev, key, frameID, kODNULLID, scopeFrameID);

        TRY
            ODSetWeakSURefProp(ev, storageUnit, kODNULL, kODNULL, frameID);
        CATCH_ALL
            // consume the exception
        ENDTRY
    }
}

//------------------------------------------------------------------------------
// Method:        ExternalizeContent
// Origin:        Cappuccino
//
// Description:    This method is called during exteralization of the part. The
//                content of the part should be written out.
//------------------------------------------------------------------------------

void Cappuccino::ExternalizeContent( Environment*        ev,
                                     ODStorageUnit*        storageUnit,
                                     ODDraftKey            key,
                                     ODFrame*            scopeFrame )
{
    SOM_Trace("Cappuccino","ExternalizeContent");

    WASSERT(fContent != kODNULL);
    fContent->Externalize(ev, storageUnit, key);
}

//------------------------------------------------------------------------------
// Method:        CleanseContentProperty
// Origin:        Cappuccino
//
// Description:    This method is called during exteralization of the part so that
//                the part can remove any value in the content property
//                that it cannot "accurately" write to.
//
// Note:        "Additional" values will be added to a part's content property
//                during Drag & Drop operations.
//------------------------------------------------------------------------------

void Cappuccino::CleanseContentProperty( Environment*        ev,
                                         ODStorageUnit*        storageUnit )
{
    SOM_Trace("Cappuccino","CleanseContentProperty");

    WASSERT(fContent != kODNULL);
    fContent->Prepare(ev, storageUnit, fPreferredKind);
}

//------------------------------------------------------------------------------
// Method:        CheckAndAddProperties
// Origin:        Cappuccino
//
// Description:    This method is called during externalization of the part to
//                verify that all the properties needed to persistently represent
//                the current running state of the part.
//
//                The part adds the default content property, a preferred editor
//                property (to aid in part binding), and a display frames
//                property.
//
// Note:        The function StorageUnitSetValue is a macro which simplifies
//                the use of ODByteArrary, which is required the StorageUnit
//                interface. Look in StorUtil.h/cpp for an example of using the
//                ODByteArray struct.
//------------------------------------------------------------------------------

void Cappuccino::CheckAndAddProperties( Environment*    ev,
                                        ODStorageUnit*    storageUnit )
{
    SOM_Trace("Cappuccino","CheckAndAddProperties");

    // Create our content property and preferred content property kind.
    ODSUForceFocus(ev, storageUnit, kODPropContents, fPreferredKind);

    // Since we are setting up the preferred kind property, we just write
    // out our default "kind" for the editor. We can write out the user
    // chosen kind in the ExternalizeStateInfo method.
    if ( !storageUnit->Exists(ev, kODPropPreferredKind, kODISOStr, 0) )
        SetPreferredKind(ev, storageUnit, kCappuccinoKind);

    // Add our display frame list.
    ODSUForceFocus(ev, storageUnit, kODPropDisplayFrames, kODWeakStorageUnitRefs);
}

//------------------------------------------------------------------------------
// Method:        SetDirty
// Origin:        Cappuccino
//
// Description:    This method is called by the part when the content or state of
//                the part has been modified by the user and the "Save" menu item
//                should be enabled.
//------------------------------------------------------------------------------

void Cappuccino::SetDirty( Environment*    ev )
{
    SOM_Trace("Cappuccino","SetDirty");

    // There is no need to repeatedly tell the draft we have changed;
    // once is sufficient.
    if ( !fDirty && !fReadOnlyStorage )
    {
        fDirty = kODTrue;
        ODGetDraft(ev, fSelf)->SetChangedFromPrev(ev);
    }
}

//------------------------------------------------------------------------------
// Method:        ReadPartInfo
// Origin:        ODPart
//
// Description:    When a frame is being internalized by the Draft, it will ask the
//                owner (part) to read in its info annotation on the frame.
//
//                The part uses a C++ helper class to encapsulate the information
//                we store with each frame, so we let it internalize itself from
//                the storage unit view.
//------------------------------------------------------------------------------

ODInfoType Cappuccino::ReadPartInfo( Environment*        ev,
                                     ODFrame*            frame,
                                     ODStorageUnitView*    storageUnitView )
{
    SOM_Trace("Cappuccino","ReadPartInfo");

    CFrameInfo* frameInfo = this->CreateFrameInfo(ev, frame);

    TRY
        // Ask the info class to internalize itself.
        frameInfo->InitFromStorage(ev, storageUnitView);
    CATCH_ALL
        // Clean up the allocated memory.
        ODDeleteObject(frameInfo);
        // Alert the caller.
        RERAISE;
    ENDTRY

    return (ODInfoType) frameInfo;
}

//------------------------------------------------------------------------------
// Method:        WritePartInfo
// Origin:        ODPart
//
// Description:    When a frame is being externalized by the Draft, it will ask the
//                owner (part) to write out its info annotation on the frame.
//
//                The part uses a C++ helper class to encapsulate the information
//                we store with each frame, so we let it externalize itself to
//                the storage unit view.
//------------------------------------------------------------------------------

void Cappuccino::WritePartInfo( Environment*        ev,
                                  ODInfoType            partInfo,
                                ODStorageUnitView*    storageUnitView )
{
    SOM_Trace("Cappuccino","WritePartInfo");

    ASSERT_NOT_NULL(partInfo);

    // Tell our frame info class to write itself out into the pre-
    // focused storage unit.
    ((CFrameInfo*) partInfo)->Externalize(ev, storageUnitView);
}

//------------------------------------------------------------------------------
// Method:        ClonePartInfo
// Origin:        ODPart
//
// Description:    When a frame is being cloned by the Draft, it will ask the owner
//                (part) to clone its info annotation on the frame.
//
//                The part uses a C++ helper class to encapsulate the information
//                we store with each frame, so we let it clone itself to the
//                storage unit view.
//------------------------------------------------------------------------------

void Cappuccino::ClonePartInfo( Environment*        ev,
                                ODDraftKey            key,
                                  ODInfoType            partInfo,
                                ODStorageUnitView*    storageUnitView,
                                ODFrame*            scopeFrame )
{
    SOM_Trace("Cappuccino","ClonePartInfo");

    ASSERT_NOT_NULL(partInfo);

    // Tell our frame info class to write itself out into the pre-
    // focused storage unit.
    ((CFrameInfo*) partInfo)->CloneInto(ev, key, storageUnitView, scopeFrame);
}

//------------------------------------------------------------------------------
// Method:        SetContent
// Origin:        Cappuccino
//
// Description:    This method is called when the content of the part should be
//                changed to the new content object.  This function will then
//                set the part to be dirty, notify the frames that the content
//                has been updated, and invalidate the frames so that they will
//                be redrawn with the new content.
//------------------------------------------------------------------------------

void Cappuccino::SetContent( Environment*            ev,
                             CCappuccinoContent*    newContent )
{
    if ( newContent )
        newContent->Acquire();

    TRY
        if ( fContent )
            fContent->Release();
    CATCH_ALL
        if ( newContent )
            newContent->Release();
        RERAISE;
    ENDTRY

    fContent = newContent;

    // Set the part dirty and cause all of the necessary frames to get redrawn.
    this->HandleChange(ev);
}

//------------------------------------------------------------------------------
// Method:        SetSettings
// Origin:        Cappuccino
//
// Description:    This method is called when the settings of the part should be
//                changed to the new contents.  This function will then set the
//                part to be dirty, notify the frames that the content has been
//                updated, and invalidate the frames so that they will be
//                redrawn with the new content.
//------------------------------------------------------------------------------

void Cappuccino::SetSettings( Environment*        ev,
                              CSettings*        newSettings )
{
    if ( newSettings )
        newSettings->Acquire();

    TRY
        if ( fSettings )
            fSettings->Release();
    CATCH_ALL
        if ( newSettings )
            newSettings->Release();
        RERAISE;
    ENDTRY

    fSettings = newSettings;

    // Set the part dirty and cause all of the necessary frames to get redrawn.
    this->HandleChange(ev);
}

//------------------------------------------------------------------------------
// Method:        HandleChange
// Origin:        Cappuccino
//
// Description:    This method is called when the content of the part or some
//                other information has changed such that we need to redraw our
//                content, mark our frames as updated, and set the part to be
//                dirty.
//------------------------------------------------------------------------------

void Cappuccino::HandleChange( Environment* ev )
{
    this->SetDirty(ev);
    this->ContentUpdated(ev);
    this->InvalidateFrameViews(ev);
}

//==============================================================================
#pragma mark    • Extensions •
//==============================================================================

//------------------------------------------------------------------------------
// Method:        HasExtension
// Origin:        ODPart
//
// Description:    The method is called when something wants to know if this
//                part supports a particular type of extension.
//------------------------------------------------------------------------------

ODBoolean Cappuccino::HasExtension( Environment*    ev,
                                    ODType            extensionName )
{
    SOM_Trace("Cappuccino","HasExtension");

#ifndef qViewerBuild
    // We don't want to include our settings extension if we're in a read only
    // storage unit, because we can't allow changing of the settings in that case.
    return ( (ODISOStrEqual(extensionName, kODSettingsExtension) && !fReadOnlyStorage)
          || ODISOStrEqual(extensionName, kODExtSemanticInterface) );
#else
    return ( ODISOStrEqual(extensionName, kODExtSemanticInterface) );
#endif
}

//------------------------------------------------------------------------------
// Method:        AcquireExtension
// Origin:        ODPart
//
// Description:    The method is called when the part is being asked for
//                a particular extension.
//------------------------------------------------------------------------------

ODExtension* Cappuccino::AcquireExtension( Environment*        ev,
                                           ODType            extensionName )
{
    SOM_Trace("Cappuccino","AcquireExtension");

#ifndef qViewerBuild
    if ( ODISOStrEqual(extensionName, kODSettingsExtension) )
    {
        if ( fSettingsExtension == kODNULL )
        {
            fSettingsExtension = new som_CappuccinoSettingsExtension;
            THROW_IF_NULL(fSettingsExtension);
            fSettingsExtension->InitSettingsExtension(ev, fSelf);
        }

        ODAcquireObject(ev, fSettingsExtension);
        return fSettingsExtension;
    }
#endif

    if ( ODISOStrEqual(extensionName, kODExtSemanticInterface) )
    {
        if ( fSemanticInterface == kODNULL )
        {
            this->ConstructSemanticInterface(ev);
        }

        ODAcquireObject(ev, fSemanticInterface);
        return fSemanticInterface;
    }

    return kODNULL;
}

//------------------------------------------------------------------------------
// Method:        ReleaseExtension
// Origin:        ODPart
//
// Description:    The method is called when the last instance of an extension
//                belonging to this part has been released.
//
//                NOTE: This routine, unlike it's SOM counterpart, returns a
//                Boolean value indicating whether the extension was one we knew
//                about.  If not (and only if not), the SOM class must call the
//                parent class to see if it knows about the extension.
//------------------------------------------------------------------------------

ODBoolean Cappuccino::ReleaseExtension( Environment*    ev,
                                        ODExtension*     extension )
{
    SOM_Trace("Cappuccino","ReleaseExtension");

#ifndef qViewerBuild
    if ( ODObjectsAreEqual(ev, extension, fSettingsExtension) )
    {
        ODDeleteObject(fSettingsExtension);
        return kODTrue;
    }
#endif

    if ( ODObjectsAreEqual(ev, extension, fSemanticInterface) )
    {
        ODDeleteObject(fSemanticInterface);
        return kODTrue;
    }

    return kODFalse;
}

//==============================================================================
#pragma mark    • Layout •
//==============================================================================

//------------------------------------------------------------------------------
// Method:        DisplayFrameAdded
// Origin:        ODPart
//
// Description:    This method is called in response to a frame being created for
//                the part.
//
//                The part records the existence of a new display frame in its
//                internal display frame list, as well as, verifies that the frame
//                is "set up" correctly (ie. valid viewType). The part also
//                creates and stores its "frame info" class in the new frame.
//------------------------------------------------------------------------------

void Cappuccino::DisplayFrameAdded( Environment*    ev,
                                       ODFrame*        frame )
{
    SOM_Trace("Cappuccino","DisplayFrameAdded");

    ASSERT_NOT_NULL(frame);

    // If we are being embedded in another part, the presentation field
    // will (most likely) be unset; we need to set it something meaningful.
    // The view field may also be unset, if so, we prefer to be displayed
    // in a frame view.
    if ( frame->GetPresentation(ev) != gGlobals->fMainPresentation )
        frame->SetPresentation(ev, gGlobals->fMainPresentation);

    if ( frame->GetViewType(ev) == kODNullTypeToken )
        frame->SetViewType(ev, gGlobals->fFrameView);

    // Hang our "state" info off of the new display frame. We use
    // the CFrameInfo object for activation, updating, and window
    // maintenance.
    CFrameInfo* frameInfo = this->CreateFrameInfo(ev, frame);
    frame->SetPartInfo(ev, (ODInfoType) frameInfo);

    // If the frame being added is a root frame, we know that a window
    // is associated with this frame. Notify ourselves that we need to
    // clean it up when the frame goes away.
    if ( frame->IsRoot(ev) )
        frameInfo->SetShouldDisposeWindow(kODTrue);

    // The proxy class will refcount the frame passed to it, so we
    // don't need to worry about refcounting the display frame.
    CFrameProxy* proxy = new CFrameProxy;
    proxy->InitFrameProxy(ev, frame);

    // Add the proxy to the display frame collection.
    fDisplayFrames->Add(proxy);

#ifndef qViewerBuild
    // Since we support drag-and-drop, turn it on.
    frame->SetDroppable(ev, kODTrue);
#endif

    // Since we maintain a persistent list of weak references to our
    // display frames, having one added to the part dirties it, but only
    // if the frame is persistent.
    if ( frame->GetStorageUnit(ev) != kODNULL )
        this->SetDirty(ev);
}

//------------------------------------------------------------------------------
// Method:        DisplayFrameConnected
// Origin:        ODPart
//
// Description:    This method is called when one of our display frames, previously
//                written out, is internalized. This method is called instead of
//                DisplayFrameAdded because a "new" frame is not being created;
//                an existing one is being reconstituted.
//
//                The part first checks to see if we can match its frame to an
//                ID in the Display frame list; if so, we put the frame into the
//                proxy. For frames we do not recognize, just add them.
//
// Warning:        This method may be called during editor swapping, with a frame
//                not recognized by the part. This is ok. Just treat the case as
//                if a "new" frame were being added to the part.
//------------------------------------------------------------------------------

void Cappuccino::DisplayFrameConnected( Environment*    ev,
                                        ODFrame*        frame )
{
    SOM_Trace("Cappuccino","DisplayFrameConnected");

    // Iterate over our display collection to match the frame with
    // an existing proxy with the correct frame ID. If we find it,
    // replace the ID with the actual frame. If we don't find it,
    // treat it as a newly "added" frame.
    ODBoolean found = kODFalse;
    CListIterator fiter(fDisplayFrames);
    for ( CFrameProxy* proxy = (CFrameProxy*) fiter.First();
            fiter.IsNotComplete(); proxy = (CFrameProxy*) fiter.Next() )
    {
        if ( proxy->GetID() == frame->GetID(ev) )
        {
            // The proxy class will refcount the frame passed to it, so we
            // don't need to worry about refcounting the display frame.
            proxy->SetFrame(ev, frame);
            found = kODTrue;
        }
    }

    // Parts typically operate under the assumption that they have previous
    // knowledge of a frame before it is connected to it. This knowledge
    // should come from having read in the frame reference when the part
    // was internalized. If the frame is an "unknown", the part was probably
    // bound to another editors storage unit because the editor is missing or
    // the user changed the editor in the Info dialog.
    if ( found )
    {
        // If a display frame is connected to us with an unrecognizable
        // presentation, we need to set it to something meaningful.

        if ( frame->GetPresentation(ev) != gGlobals->fMainPresentation )
            frame->SetPresentation(ev, gGlobals->fMainPresentation);

        if ( frame->IsRoot(ev) )
        {
            // If the frame being added is a root frame, we know that a window
            // is associated with this frame. Notify ourselves that we need to
            // clean it up when the frame goes away.
            CFrameInfo* frameInfo = CFrameInfo::GetFrameInfo(ev, frame);
            frameInfo->SetShouldDisposeWindow(kODTrue);

            // In addition, we need to verify that the frame is in "frame" view.
            // If the user dragged an icon from a document to Finder and then
            // opens the resultant document, the view would be "icon". However
            // displaying a icon is useless, so we need to change the view to
            // frame.
            if ( frame->GetViewType(ev) != gGlobals->fFrameView )
                frame->SetViewType(ev, gGlobals->fFrameView);
        }

#ifndef qViewerBuild
        // Since we support drag-and-drop, turn it on.
        frame->SetDroppable(ev, kODTrue);
#endif
    }
    else
    {
        // If an unrecognizable frame is connected to us, treat it like a "new"
        // frame and call our method to add it.
        this->DisplayFrameAdded(ev, frame);
    }
}

//------------------------------------------------------------------------------
// Method:        DisplayFrameRemoved
// Origin:        ODPart
//
// Description:    This method is called in response to a frame being removed from
//                the part.
//
//                The part removes the frame from its internal display frame list
//                and reliquishes any foci that it still owned. Lastly, if the
//                frame has a source frame (it was the root frame of a part
//                window), we will record the part window bounds so that any
//                subsequent part windows opened on the source frame will appear
//                in the same location.
//------------------------------------------------------------------------------

void Cappuccino::DisplayFrameRemoved( Environment*    ev,
                                      ODFrame*        frame )
{
    SOM_Trace("Cappuccino","DisplayFrameRemoved");

    ASSERT_NOT_NULL(frame);

    TRY
        CFrameInfo* frameInfo = CFrameInfo::GetFrameInfo(ev, frame);

        // Make sure the frame going away does not own any foci. Forgetting
        // to do this, will cause a "refcounting" error when the frame
        // is deleted by the draft.
        this->RelinquishAllFoci(ev, frame);

        // If removing a child window, show zoom rects back to source.
        // NOTE: This has to be done before CleanupDisplayFrame because
        // CleanupDisplayFrame will remove the relationship.
        if ( frame->IsRoot(ev) && frameInfo->HasSourceFrame() )
        {
            TempODWindow window = frame->AcquireWindow(ev);
            this->ZoomPartWindow(ev, frameInfo->GetSourceFrame(ev),
                                 window, kWindowClosing);
        }

        // Clean up the display frame.
        this->CleanupDisplayFrame(ev, frame, kFrameRemoved);
        // Clean up any associated window.
        this->CleanupWindow(ev, frame);
        // Dispose of the frame's runtime state info.
        frame->SetPartInfo(ev, (ODInfoType) kODNULL);
        ODDeleteObject(frameInfo);

        // Remove the display frame from our collection.
        CListIterator fiter(fDisplayFrames);
        for ( CFrameProxy* proxy = (CFrameProxy*) fiter.First();
                fiter.IsNotComplete(); proxy = (CFrameProxy*) fiter.Next() )
        {
            if ( ODObjectsAreEqual(ev, proxy->GetFrame(ev), frame) )
            {
                // Delete the proxy object and its contents. The frame's
                // refcount will be decremented in the proxy destructor.
                fiter.RemoveCurrent();
                delete proxy;
            }
        }

        // Since we maintain a persistent list of weak references to our
        // display frames, having one removed from the part dirties it.
        this->SetDirty(ev);

    CATCH_ALL
        // Alert the user of the problem.
        this->DoDialogBox(ev, frame, kErrorBoxID, kErrRemoveFrame);
        // Change the exception value, so the DocShell doesn't display an
        // error dialog.
        SetErrorCode(kODErrAlreadyNotified);
        // Alert the caller.
        RERAISE;
    ENDTRY
}

//------------------------------------------------------------------------------
// Method:        DisplayFrameClosed
// Origin:        ODPart
//
// Description:    This method is called in response to a frame being closed as a
//                result of the document having been closed by the user.
//
//                The part behaves much the same way that it would if a frame were
//                removed (see above), except that we don't need to cache runtime
//                information.
//------------------------------------------------------------------------------

void Cappuccino::DisplayFrameClosed( Environment*    ev,
                                     ODFrame*        frame )
{
    SOM_Trace("Cappuccino","DisplayFrameClosed");

    ASSERT_NOT_NULL(frame);

    TRY
        CFrameInfo* frameInfo = CFrameInfo::GetFrameInfo(ev, frame);

        // Make sure the frame going away does not own any foci. Forgetting
        // to do this, will cause a "refcounting" error when the frame
        // is deleted by the draft.
        this->RelinquishAllFoci(ev, frame);

        // Clean up the display frame.
        this->CleanupDisplayFrame(ev, frame, kFrameClosed);
        // Clean up any associated window.
        this->CleanupWindow(ev, frame);
        // Dispose of the frame's runtime state info.
        frame->SetPartInfo(ev, (ODInfoType) kODNULL);
        ODDeleteObject(frameInfo);

        // Remove the display frame from our collection.
        CListIterator fiter(fDisplayFrames);
        for ( CFrameProxy* proxy = (CFrameProxy*) fiter.First();
                fiter.IsNotComplete(); proxy = (CFrameProxy*) fiter.Next() )
        {
            if ( proxy->GetID() == frame->GetID(ev) )
            {
                // Release the frame reference, but don't get rid of the
                // proxy object because "closed" frames may be reconnected
                // before the document is closed.
                proxy->Purge(ev);
            }
        }

    CATCH_ALL
        // Alert the user of the problem.
        this->DoDialogBox(ev, frame, kErrorBoxID, kErrRemoveFrame);
        // Change the exception value, so the DocShell doesn't display an
        // error dialog.
        SetErrorCode(kODErrAlreadyNotified);
        // Alert the caller.
        RERAISE;
    ENDTRY
}

//------------------------------------------------------------------------------
// Method:        CleanupDisplayFrame
// Origin:        Cappuccino
//
// Description:    This method is called when a frame has been closed or removed.
//                The method cleans up the references and state information stored
//                in the CFrameInfo class.
//------------------------------------------------------------------------------

void Cappuccino::CleanupDisplayFrame(    Environment*    ev,
                                        ODFrame*        frame,
                                        ODBoolean        frameRemoved )
{
    SOM_Trace("Cappuccino","CleanupDisplayFrame");

    ASSERT_NOT_NULL(frame);

    ODError        error = noErr;
    CFrameInfo*    frameInfo = CFrameInfo::GetFrameInfo(ev, frame);

    TRY
        // If we are the root of a child window, we need to notify
        // our source frame that we are going away.
        if ( frameInfo->HasSourceFrame() )
        {
            ODFrame* sourceFrame = frameInfo->GetSourceFrame(ev);
            CFrameInfo* sourceFrameInfo = CFrameInfo::GetFrameInfo(ev, sourceFrame);

            if ( frameRemoved )
            {
                // Invalidate the source frame. We do this because the
                // source frame may have a unique display when it has
                // been opened into a part window. This forces the
                // frame to redraw "not opened".

                // Here, we check to see if the source of the frame is frame
                // view, in which case we don't invalidate it because our
                // frame view doesn't draw any differently if there was a
                // child window open.
                if ( sourceFrame->GetViewType(ev) != gGlobals->fFrameView )
                    sourceFrame->Invalidate(ev, kODNULL, kODNULL);
            }

            // Tell the source frame that its dependent is going away.
            sourceFrameInfo->ReleaseDependentFrame(ev);

            // Release our reference to the source frame.
            frameInfo->ReleaseSourceFrame(ev);

            // If the frame is the root, it is a part window going away
            // and we need to notify our source frame that it no longer
            // has a part window.
            if ( frame->IsRoot(ev) )
                sourceFrameInfo->SetPartWindow(ev, kODNULL);
        }
    CATCH_ALL
        error = ErrorCode();
    ENDTRY

    TRY
        // If the frame was removed from the document, we need to remove
        // any child window displaying that frame.
        if ( frameRemoved )
        {
            // If we have a child window, we need to close it.
            ODWindow* window = frameInfo->AcquirePartWindow(ev);

            if ( window )
            {
                frameInfo->SetPartWindow(ev, kODNULL);
                window->CloseAndRemove(ev);
            }
        }
    CATCH_ALL
        error = ErrorCode();
    ENDTRY

    TRY
        // If we have dependent frames, we need to notify them that we
        // are going away.

        if ( frameInfo->HasDependentFrame() )
        {
            // Get the frame that is dependent on this one. We can safely
            // do this because we only reference our own display frames.
            ODFrame* dependentFrame = frameInfo->GetDependentFrame(ev);
            CFrameInfo* dependentFrameInfo = CFrameInfo::GetFrameInfo(ev, dependentFrame);

            // Tell the dependent frame that its source is going away.
            dependentFrameInfo->ReleaseSourceFrame(ev);

            // Release our reference to the dependent frame.
            frameInfo->ReleaseDependentFrame(ev);
        }
    CATCH_ALL
        error = ErrorCode();
    ENDTRY

    // If anything went wrong, signal an error.
    THROW_IF_ERROR(error);
}

//------------------------------------------------------------------------------
// Method:        AttachSourceFrame
// Origin:        ODPart
//
// Description:    If the part which we are contained in is opened into a part
//                window, it is required to iterate over its embedded frames and
//                add new display frames in the part window. After each new
//                embedded frame is created, this method will be called.
//
//                Given all that, and given our lack of interesting
//                content, we just validate the frame and attach it to its source.
//------------------------------------------------------------------------------

void Cappuccino::AttachSourceFrame( Environment*    ev,
                                    ODFrame*        frame,
                                    ODFrame*        sourceFrame )
{
    SOM_Trace("Cappuccino","AttachSourceFrame");

    ASSERT_NOT_NULL(frame);

    // Tell the new frame about its source.
    CFrameInfo* frameInfo = CFrameInfo::GetFrameInfo(ev, frame);
    frameInfo->SetSourceFrame(ev, sourceFrame);

    // And tell the source about its new dependent.
    frameInfo = CFrameInfo::GetFrameInfo(ev, sourceFrame);
    frameInfo->SetDependentFrame(ev, frame);

    // In both cases, refcounting of the frame and sourceFrame is
    // handled by the CFrameInfo class.
}

//------------------------------------------------------------------------------
// Method:        ViewTypeChanged
// Origin:        ODPart
//
// Description:    This method is called in response to one of our display frame's
//                viewType field being modified. We call this method on ourselves
//                when new display frames are added, but it call also be called
//                when the user changes the view in the "part info" dialog.
//
//                The part first loads the appropriate view icons if needed and
//                then calculates a new "used" shape based on the bounds of the
//                new view type. If any problems occur while changing the view,
//                the part defaults back to frame view (the part's default view).
//------------------------------------------------------------------------------

void Cappuccino::ViewTypeChanged( Environment*    ev,
                                  ODFrame*        frame )
{
    SOM_Trace("Cappuccino","ViewTypeChanged");

    // Change this frame's used shape to match the new view setting.
    TempODShape newUsedShape = this->CalcNewUsedShape(ev, frame);

    frame->Invalidate(ev, kODNULL, kODNULL);
    frame->ChangeUsedShape(ev, newUsedShape, kODNULL);
    frame->Invalidate(ev, kODNULL, kODNULL);
}

//------------------------------------------------------------------------------
// Method:        PresentationChanged
// Origin:        ODPart
//
// Description:    This method is called when the presentation of a frame has been
//                changed.
//------------------------------------------------------------------------------

void Cappuccino::PresentationChanged( Environment*    ev,
                                      ODFrame*        frame )
{
    SOM_Trace("Cappuccino","PresentationChanged");

}

//------------------------------------------------------------------------------
// Method:        SequenceChanged
// Origin:        ODPart
//
// Description:    This method is called when a frame's place in a sequence has
//                been changed.
//------------------------------------------------------------------------------

void Cappuccino::SequenceChanged( Environment*    ev,
                                  ODFrame*        frame )
{
    SOM_Trace("Cappuccino","SequenceChanged");

}

//------------------------------------------------------------------------------
// Method:        ContainingPartPropertiesUpdated
// Origin:        ODPart
//
// Description:    This method is called when the containing part attempts to
//                change some properties of the embedded part.  We should examine
//                the properties of the storage unit for anything we understand.
//------------------------------------------------------------------------------

void Cappuccino::ContainingPartPropertiesUpdated( Environment*        ev,
                                                  ODFrame*            frame,
                                                  ODStorageUnit*    propertyUnit )
{
    SOM_Trace("Cappuccino","ContainingPartPropertiesUpdated");

}

//------------------------------------------------------------------------------
// Method:        CalcNewUsedShape
// Origin:        Cappuccino
//
// Description:    This method is called in response to one of display frame's view
//                being changed. The method calculates the appropriate usedShape
//                for the new view type.
//------------------------------------------------------------------------------

ODShape* Cappuccino::CalcNewUsedShape( Environment*        ev,
                                         ODFrame*            frame )
{
    SOM_Trace("Cappuccino","CalcNewUsedShape");

    ASSERT_NOT_NULL(frame);

    ODShape* usedShape = kODNULL;
    ODVolatile(usedShape);

    // If the view is "frame", we intentionally return a nil shape;
    // doing so, will reset the used shape to equal the frame shape.

    ODTypeToken view = frame->GetViewType(ev);

    if ( view == gGlobals->fLargeIconView ||
         view == gGlobals->fSmallIconView ||
         view == gGlobals->fThumbnailView )
    {
        RgnHandle usedRgn = ODNewRgn();
        TRY
            Rect bounds;
            if ( view == gGlobals->fLargeIconView || view == gGlobals->fSmallIconView )
            {
                CUsingLibraryResources res;

                // Set the bounds rect for the icon size.
                SetRect(&bounds, 0, 0,
                        (view == gGlobals->fLargeIconView) ? kODLargeIconSize : kODSmallIconSize,
                        (view == gGlobals->fLargeIconView) ? kODLargeIconSize : kODSmallIconSize);

                // Convert the icon mask into a Region.
                THROW_IF_ERROR( IconIDToRgn(usedRgn, &bounds, atAbsoluteCenter, kBaseResourceID) );
            }
            else if ( view == gGlobals->fThumbnailView )
            {
                PicHandle thumbnail = this->GenerateThumbnail(ev, frame);

                if ( thumbnail )
                    bounds = (**thumbnail).picFrame;
                else
                    SetRect(&bounds, 0, 0, kODThumbnailSize, kODThumbnailSize);

                RectRgn(usedRgn,&bounds);
            }

            usedShape = frame->CreateShape(ev);
            usedShape->SetQDRegion(ev, usedRgn);

        CATCH_ALL
            ODSafeReleaseObject(usedShape);
            ODDisposeHandle((ODHandle) usedRgn);
            usedShape = kODNULL;
        ENDTRY
    }

    return usedShape;
}

//------------------------------------------------------------------------------
// Method:        UpdateFrame
// Origin:        Cappuccino
//
// Description:    This method is called in response to one of our
//------------------------------------------------------------------------------

void Cappuccino::UpdateFrame( Environment*    ev,
                             ODFrame*        frame,
                             ODTypeToken    view,
                             ODShape*        usedShape )
{
    SOM_Trace("Cappuccino","UpdateFrame");

    TRY
        // Update the frame to have the new view and UsedShape.
        frame->Invalidate(ev, kODNULL, kODNULL);
        frame->SetViewType(ev, view);
        frame->ChangeUsedShape(ev, usedShape, kODNULL);
        frame->Invalidate(ev, kODNULL, kODNULL);
    CATCH_ALL
        // Failing isn't great, but we can live with it, so don't set ev.
    ENDTRY
}

//------------------------------------------------------------------------------
// Method:        GenerateThumbnail
// Origin:        Cappuccino
//
// Description:    This method is called by the part to generate a thumbnail view
//                from the current content.
//
//                The part has no content, so we merely load a picture.
//------------------------------------------------------------------------------

PicHandle Cappuccino::GenerateThumbnail( Environment*    ev,
                                         ODFrame*        frame )
{
    SOM_Trace("Cappuccino","GenerateThumbnail");

    if ( gGlobals->fThumbnail == kODNULL )
    {
        // In cases where a part has been instantiated from scratch and has no
        // content (yet), it is appropriate to display a PICT or some graphic
        // in place of a "real" thumbnail.

        LoadThumbnail(ev, &gGlobals->fThumbnail);

        // If we were unable to load the PICT resource for whatever reason
        // we will default back to a "frame" view and throw the Resource
        // Manager error as an exception.
        if ( gGlobals->fThumbnail == kODNULL )
        {
            frame->SetViewType(ev, gGlobals->fFrameView);

            // There is a bug in ResError, when resources are not found,
            // which may cause noErr to be returned. If that is the case,
            // we throw resNotFound.
            THROW_IF_ERROR((ODError) ResError());
            THROW(resNotFound);
        }
    }

    return (PicHandle) gGlobals->fThumbnail;
}

//------------------------------------------------------------------------------
// Method:        FrameShapeChanged
// Origin:        ODPart
//
// Description:    This method is called in response to a frame's shape being
//                altered, either by the user or the part we are embedded in.
//------------------------------------------------------------------------------

void Cappuccino::FrameShapeChanged( Environment*    ev,
                                    ODFrame*        frame )
{
    SOM_Trace("Cappuccino","FrameShapeChanged");

    // Adjust the "used" shape for the new frame shape.
    TempODShape usedShape = this->CalcNewUsedShape(ev, frame);
    frame->ChangeUsedShape(ev, usedShape, kODNULL);
}

//------------------------------------------------------------------------------
// Method:        Open
// Origin:        ODPart
//
// Description:    This method is called when OpenDoc, a containing part, or the
//                active editor would like to open a frame into a seperate window.
//                If a source frame is passed into this method, the editor is
//                being asked one of two things. If the frame is the root, we are
//                being asked to open an existing document. If the frame is not
//                the root, we are being asked to open a part window. If a source
//                frame is not specified, the editor is being asked to open a new
//                window.
//------------------------------------------------------------------------------

ODID Cappuccino::Open( Environment*    ev, ODFrame* frame )
{
    SOM_Trace("Cappuccino","Open");

    ODID windowID;
    TempODWindow window(kODNULL);

    WindowProperties* windowProperties = kODNULL;
    ODVolatile(windowProperties);

    TRY
        // Because the frame parameter being passed to us can be one of
        // three things, we must determine what it is; either the root
        // frame of a existing document, the source frame for a part
        // window, or null if we are opening a new document.

        if ( frame == kODNULL )
        {
            // Calculate the bounding rectangle for a new window
            Rect windowRect = this->CalcPartWindowSize(ev, kODNULL);
            // Get the default setting for a document window.
            windowProperties = this->GetDefaultWindowProperties(ev, kODNULL, &windowRect);
            // Create a Mac Window and register it with OpenDoc.
            window = this->CreateWindow(ev, kODNULL, kODFrameObject, windowProperties);
        }
        else if ( frame->IsRoot(ev) )
        {
            // Get the previously saved settings for the document window.
            windowProperties = this->GetSavedWindowProperties(ev, frame);

            if ( windowProperties == kODNULL )
            {
                // Calculate the bounding rectangle for a new window
                Rect windowRect = this->CalcPartWindowSize(ev, frame);
                // Get the default setting for a document window.
                windowProperties = this->GetDefaultWindowProperties(ev, kODNULL, &windowRect);
            }

            // Create a Mac Window and register it with OpenDoc.
            window = this->CreateWindow(ev, frame, kODFrameObject, windowProperties);

            // We release the source frame here because we didn't call
            // EndGetWindowProperties and becuase we are done with it.
            ODReleaseObject(ev, windowProperties->sourceFrame);
        }
        else // frame is a source frame
        {
            window = this->AcquireFramesWindow(ev, frame);

            if ( window == kODNULL )
            {
                // Calculate the bounding rectangle for a new window
                Rect windowRect = this->CalcPartWindowSize(ev, frame);
                // Get the default setting for a document window.
                windowProperties = this->GetDefaultWindowProperties(ev, frame, &windowRect);
                // Create a Mac Window and register it with OpenDoc.
                window = this->CreateWindow(ev, kODNULL, kODFrameObject, windowProperties);

                // Tell the source frame that it is opened in a part window.
                CFrameInfo* frameInfo = CFrameInfo::GetFrameInfo(ev, frame);
                frameInfo->SetPartWindow(ev, window);

                this->ZoomPartWindow(ev, frame, window, kWindowOpening);
            }
        }

        // Create the window's root facet.
        window->Open(ev);
        // Make the window visible.
        window->Show(ev);
        // Activate and select the window.
        window->Select(ev);

        // Cleanup allocate memory.
        ODDeleteObject(windowProperties);

        // Get window id to return.
        windowID = (window ? window->GetID(ev) : kODNULLID);

    CATCH_ALL
        // If we threw early, the source frame's refcount may be too high.
        if ( windowProperties )
            ODSafeReleaseObject(windowProperties->sourceFrame);
        // Cleanup the created items.
        ODDeleteObject(windowProperties);
        windowID = kODNULLID;
        // Alert the caller.
        RERAISE;
    ENDTRY

    return windowID;
}

//------------------------------------------------------------------------------
// Method:        CreateFrameInfo
// Origin:        Cappuccino
//
// Description:    This method is called by the part when a CFrameInfo object
//                needs to be created for a frame.
//------------------------------------------------------------------------------

CFrameInfo* Cappuccino::CreateFrameInfo( Environment*        ev,
                                            ODFrame*            frame )
{
    return new CFrameInfo(fSession);
}

//------------------------------------------------------------------------------
// Method:        ZoomPartWindow
// Origin:        Cappuccino
//
// Description:    This method is called by the part when a frame is being opened
//                or closed in the case that zooming rectangles should be shown.
//------------------------------------------------------------------------------

void Cappuccino::ZoomPartWindow( Environment*        ev,
                                    ODFrame*            frame,
                                    ODWindow*            window,
                                    ODBoolean            isZoomingOpen )
{
    ASSERT_NOT_NULL(frame);
    ASSERT_NOT_NULL(window);

    const ODSShort kNumZoomSteps = 12;

    Rect frameRect;
    {
        // We need to know which facet of the frame we are opening to position
        // the child window.
        ODFacet* zoomFacet = kODNULL;

        TRY
            zoomFacet = this->GetActiveFacetForFrame(ev, frame);
        CATCH_ALL
        ENDTRY

        // In case there isn't an active facet for the frame, .
        if ( zoomFacet == kODNULL )
        {
            TempODFrameFacetIterator iter(ev, frame);
            zoomFacet = iter.First();
        }

        if ( zoomFacet != kODNULL )
        {
            // For doing the zoom rects, we need the to know the area of the
            // document the frame occupies. We do this by getting the bouding
            // box and offsetting it by the aggregate external window transform
            // of the facet.
            TempODTransform windowFrameTransform = zoomFacet->AcquireWindowFrameTransform(ev, kODNULL);
            TempODShape boundsShape = ODCopyAndRelease(ev, zoomFacet->GetFrame(ev)
                                                            ->AcquireFrameShape(ev, kODNULL));

            // Translate the bounds rect into window coordinates.
            boundsShape->Transform(ev, windowFrameTransform);

            // Get and convert the bounding box into a QuickDraw rectangle.
            ODRect bbox;
            boundsShape->GetBoundingBox(ev, &bbox);
            FixedToIntRect(bbox, frameRect);

            // Set the port and origin so we can convert the rect to
            // global Window Mgr coordinates.
            SetPort(zoomFacet->GetCanvas(ev)->GetQDPort(ev));
            SetOrigin(0, 0);

            // Convert the local coordinates to global Window Mgr coordinates.
            LocalToGlobal((Point*) &frameRect.top);
            LocalToGlobal((Point*) &frameRect.bottom);
        }
    }

    Rect windowRect;
    {
        ODPlatformWindow platformWindow = window->GetPlatformWindow(ev);

        windowRect = platformWindow->portRect;
        windowRect.top -= kMacWindowTitleBarHeight;

        // Set the port and origin so we can convert the rect to
        // global Window Mgr coordinates.
        SetPort(platformWindow);
        SetOrigin(0, 0);

        // Convert the local coordinates to global Window Mgr coordinates.
        LocalToGlobal((Point*) &windowRect.top);
        LocalToGlobal((Point*) &windowRect.bottom);
    }

    Rect fromRect = isZoomingOpen ? frameRect  : windowRect;
    Rect toRect   = isZoomingOpen ? windowRect : frameRect;

    if ( !isZoomingOpen )
        window->Hide(ev);

    (void) ZoomRects(&fromRect, &toRect, kNumZoomSteps,
                     isZoomingOpen ? zoomAccelerate : zoomDecelerate);
}

//------------------------------------------------------------------------------
// Method:        AcquireFramesWindow
// Origin:        Cappuccino
//
// Description:    This method is called by the part when a frame, that has been
//                previously opened, is being opened again.
//
//                The method retrieves the existing window for the frame and
//                returns it.
//------------------------------------------------------------------------------

ODWindow* Cappuccino::AcquireFramesWindow(    Environment*    ev,
                                               ODFrame*        frame )
{
    SOM_Trace("Cappuccino","GetFramesWindow");

    ASSERT_NOT_NULL(frame);

    CFrameInfo* frameInfo = CFrameInfo::GetFrameInfo(ev, frame);
    return frameInfo->AcquirePartWindow(ev);
}

//------------------------------------------------------------------------------
// Method:        CreateWindow
// Origin:        Cappuccino
//
// Description:    This method is called by the part when a window needs to be
//                created for a frame being opened.
//
//                The part uses the information passed in windowProperties to
//                create the appropriate window. The generated window is
//                registered with OpenDoc as a new window (RegisterWindow) or as a
//                window from an existing document (RegisterWindowForFrame).
//------------------------------------------------------------------------------

ODWindow* Cappuccino::CreateWindow( Environment*         ev,
                                    ODFrame*            frame,
                                    ODType                frameType,
                                    WindowProperties*    windowProperties)
{
    SOM_Trace("Cappuccino","CreateWindow");

    ODPlatformWindow    platformWindow    = kODNULL;
    ODWindow*            window            = kODNULL;

    // Using the name and the calculated rectangle, create a new window.
    // Note that we are allocating the window record in temp mem using
    // the OpenDoc memory mgr. This helps reduce app heap usage.
    // In addition, OpenDoc requires that all new windows be initially hidden
    // so that it can correctly layer windows/palettes.
    platformWindow = NewCWindow((Ptr)ODNewPtr(sizeof(WindowRecord)),
                                &(windowProperties->boundsRect),
                                windowProperties->title,
                                kODFalse,                             // visible
                                windowProperties->procID,
                                (WindowPtr)-1L,
                                windowProperties->hasCloseBox,
                                windowProperties->refCon);

    if ( platformWindow )
    {
        TRY
            ODWindowState* windowState = fSession->GetWindowState(ev);

            // Shoud the window be saved in the document? Yes if the root frame is
            // persistent.
            ODBoolean saveWindow = ODISOStrEqual(frameType, kODFrameObject);

            // Tell the window object that we will be disposing the window record
            // when the root frame is closed/removed.
            ODBoolean shouldDispose = kODFalse;

            // Determine whether we are creating a new window (frame is null),
            // or opening a previous saved window (frame is valid).

            if ( frame == kODNULL )
            {
                // Tell OpenDoc about it by creating an OpenDoc window object.
                window = windowState->
                            RegisterWindow(ev,
                                platformWindow,                    // Macintosh WindowPtr
                                frameType,                        // Frame type (Persistent/Non-persistent)
                                windowProperties->isRootWindow,    // Is this a document window?
                                windowProperties->isResizable,    // Is this window resizeable?
                                windowProperties->isFloating,    // Is this window floating?
                                saveWindow,                        // Should this window be persistent?
                                shouldDispose,                    // (see comment above)
                                fSelf,                            // Part reference to us
                                gGlobals->fFrameView,            // What view should the window have?
                                gGlobals->fMainPresentation,    // What presentation should the window have?
                                windowProperties->sourceFrame);    // The display frame being opened, if any
            }
            else
            {
                // Tell OpenDoc about it by creating an OpenDoc window object.
                window = windowState->
                            RegisterWindowForFrame(ev,
                                platformWindow,                    // Macintosh WindowPtr
                                frame,                             // Frame type (Persistent/Non-persistent)
                                windowProperties->isRootWindow,    // Is this a document window?
                                windowProperties->isResizable,    // Is this window resizeable?
                                windowProperties->isFloating,    // Is this window floating?
                                saveWindow,                        // Should this window be persistent?
                                shouldDispose,                    // (see comment above)
                                windowProperties->sourceFrame);    // The display frame being opened, if any
            }

        CATCH_ALL
            // Cleanup Macintosh Window.
            CloseWindow(platformWindow);
            ODDisposePtr(platformWindow);
            // Get the right error message for the problem.
            ODSShort errMsgNum = (!frame && windowProperties->sourceFrame)
                                    ? kErrCantOpenPartWindow : kErrCantOpenDocWindow;
            // Alert the user of the problem.
            this->DoDialogBox(ev, frame, kErrorBoxID, errMsgNum);
            // Change the exception value, so the DocShell doesn't display an
            // error dialog.
            SetErrorCode(kODErrAlreadyNotified);
            // Alert the caller.
            RERAISE;
        ENDTRY
    }

    return window;
}

//------------------------------------------------------------------------------
// Method:        CleanupWindow
// Origin:        Cappuccino
//
// Description:    This method is called by the part when a window needs to be
//                cleaned up for a frame being closed/removed.
//
//                The part deallocates the window buffer allocated in the
//                CreateWindow() method.
//------------------------------------------------------------------------------

void Cappuccino::CleanupWindow( Environment*     ev,
                                ODFrame*        frame )
{
    SOM_Trace("Cappuccino","CleanupWindow");

    ASSERT_NOT_NULL(frame);

       TRY
        CFrameInfo*    frameInfo = CFrameInfo::GetFrameInfo(ev, frame);
        if ( frameInfo->ShouldDisposeWindow() )
        {
            TempODWindow window = frame->AcquireWindow(ev);
            THROW_IF_NULL(window);

            ODPlatformWindow windowPtr = window->GetPlatformWindow(ev);
            CloseWindow(windowPtr);
            ODDisposePtr(windowPtr);
        }
    CATCH_ALL
        this->DoDialogBox(ev, frame, kErrorBoxID, kErrWindowGone);
        // consume excpetion because it's not fatal.
    ENDTRY
}

//------------------------------------------------------------------------------
// Method:        GetDefaultWindowProperties
// Origin:        Cappuccino
//
// Description:    This method is called by the part when a new window is being
//                created. The method examines the frame which is being opened
//                a generates the default window parameters to pass to the
//                Mac Toolbox.
//------------------------------------------------------------------------------

WindowProperties*
Cappuccino::GetDefaultWindowProperties( Environment*     ev,
                                        ODFrame*        sourceFrame,
                                        Rect*            windowRect )
{
    SOM_Trace("Cappuccino","GetDefaultWindowProperties");

    WindowProperties* windowProperties = new WindowProperties;

    TRY
        // Calculate the offset for the window based on the sourceFrame.
        if ( sourceFrame )
            this->CalcPartWindowPosition(ev, sourceFrame, windowRect);
        else
            OffsetRect(windowRect, kALittleNudge,
                        GetMBarHeight() + kMacWindowTitleBarHeight);

        // Set the window bounds based on the calculated rect.
        windowProperties->boundsRect = *windowRect;

        // Get the part's name to use for the new window.
        TempODIText windowName = GetPartName(ev, fSelf, kCappuccinoCategory);
        // Convert the ODIText into a Pascal string.
        GetITextString(windowName, windowProperties->title);

        // Fill in the other fields of the Window Properties struct.

        windowProperties->procID = zoomDocProc;
        windowProperties->hasCloseBox = kODTrue;
        windowProperties->refCon = (long) kODNULL;
        windowProperties->wasVisible = kODFalse;
        windowProperties->isResizable = kODTrue;
        windowProperties->isFloating = kODFalse;
        windowProperties->isRootWindow = sourceFrame ? kODFalse : kODTrue;
        windowProperties->shouldShowLinks = kODFalse;
        windowProperties->sourceFrame = sourceFrame;
    CATCH_ALL
        // Clean up and...
        ODDeleteObject(windowProperties);
        // Alert the caller.
        RERAISE;
    ENDTRY

    return windowProperties;
}

//------------------------------------------------------------------------------
// Method:        GetSavedWindowProperties
// Origin:        Cappuccino
//
// Description:    This method is called by the part to read in saved information
//                for a window from an existing document.
//------------------------------------------------------------------------------

WindowProperties* Cappuccino::GetSavedWindowProperties( Environment*     ev,
                                                          ODFrame*        frame )
{
    SOM_Trace("Cappuccino","GetSavedWindowProperties");

    WindowProperties* windowProperties = new WindowProperties;

    // If we fail to load the window properties from storage, delete
    // the structure so the calling code will behave appropriately.
    if ( BeginGetWindowProperties(ev, frame, windowProperties) )
    {
        // Note: We don't call EndGetWindowProperties because it releases the
        // source frame, which we will need after this method returns.

        // Get the part's name to use for the new window.
        TempODIText windowName = GetPartName(ev, fSelf, kCappuccinoCategory);
        // Convert the ODIText into a Pascal string.
        GetITextString(windowName, windowProperties->title);

        // Verify the window is still visible on a monitor.

        RgnHandle windowRgn = ODNewRgn();
        ODBoolean repositionWindow = kODFalse;

        // We are only concerned with the window's title bar being
        // visible, so calcuate the titlebar rect from the current
        // window bounds.
        Rect adjustedBounds = windowProperties->boundsRect;
        adjustedBounds.bottom = adjustedBounds.top;
        adjustedBounds.top -= kMacWindowTitleBarHeight;

        // Intersect the monitor's region
        RectRgn(windowRgn, &adjustedBounds);
        SectRgn(windowRgn, GetGrayRgn(), windowRgn);

        if ( !EmptyRgn(windowRgn) )
        {
            // If the visible portion of the window is too small, we need
            // to reposition it.
            Rect intersectedBounds = (**windowRgn).rgnBBox;
            if ( (intersectedBounds.right-intersectedBounds.left < kMinHorzVisPortion) ||
                    (intersectedBounds.bottom-intersectedBounds.top < kMinVertVisPortion) )
                repositionWindow = kODTrue;
        }
        else
        {
            // If the window is completely offscreen, we need to reposition it.
            repositionWindow = kODTrue;
        }
        ODDisposeHandle((ODHandle)windowRgn);

        // If not, we need to move it so the user can see it.
        if ( repositionWindow )
        {
            Rect windowRect = (windowProperties->boundsRect);
            // Move the window to {0,0} coordinates.
            OffsetRect(&windowRect, -windowRect.left, -windowRect.top);
            // Now move the window to the default window position.
            OffsetRect(&windowRect, kALittleNudge, GetMBarHeight() + kMacWindowTitleBarHeight);
            // Save the new window position in our windowProperties.
            windowProperties->boundsRect = windowRect;
        }
    }
    else
    {
        // If we were unable to re-load window properties, dispose of the
        // struct.
        ODDeleteObject(windowProperties);
    }

    return windowProperties;
}

//------------------------------------------------------------------------------
// Method:        CalcPartWindowSize
// Origin:        Cappuccino
//
// Description:    This method is called by the part to determine what size a new
//                window shoud be.
//------------------------------------------------------------------------------

Rect Cappuccino::CalcPartWindowSize( Environment*    ev,
                                     ODFrame*        sourceFrame )
{
    SOM_Trace("Cappuccino","CalcPartWindowSize");

    const ODSShort kOnePageWidth = 600;

    Rect    windowRect;
    ODRect    frameRect;

    // If a source frame is given, the part is being asked to open one of
    // its display frames into a part window. Otherwise, we are being opened
    // as the root frame of the current document and should size the window
    // accordingly.

    // Set up the child window's size to be that of the display frame being opened.
    if ( sourceFrame )
    {
        // Retrieve the fixed point bounding box for the frame.
        TempODShape frameShape = sourceFrame->AcquireFrameShape(ev, kODNULL);
        frameShape->GetBoundingBox(ev, &frameRect);

        // Convert that into a Quickdraw rectangle.
        FixedToIntRect(frameRect, windowRect);
    }
    // Otherwise, just open a large window.
    else
    {
        // (3 * kODLargeIconSize) prevents the window from covering the volume
        // icons on the desktop which is a violation of Macintosh HI Guidelines.

        SetRect(&windowRect, 0, 0,
                  ODQDGlobals.screenBits.bounds.right - (3 * kODLargeIconSize),
                  ODQDGlobals.screenBits.bounds.bottom
                      - GetMBarHeight() - kMacWindowTitleBarHeight - kALittleNudge);

        if ( windowRect.right - windowRect.left > kOnePageWidth )
            windowRect.right = windowRect.left + kOnePageWidth;
    }

    return windowRect;
}

//------------------------------------------------------------------------------
// Method:        CalcPartWindowPosition
// Origin:        Cappuccino
//
// Description:    This method is called by the part to determine where to align
//                the new window (top left corner of the screen or tiled to a
//                frame).
//------------------------------------------------------------------------------

Rect Cappuccino::CalcPartWindowPosition( Environment*    ev,
                                         ODFrame*        frame,
                                         Rect*            partWindowBounds )
{
    SOM_Trace("Cappuccino","CalcPartWindowPosition");

    // We need to know which facet of the frame we are opening to position
    // the child window.
    ODFacet* activeFacet = this->GetActiveFacetForFrame(ev, frame);

    // This should never occur, but if it did, it would be fatal.
    // So we will just pass back the same rectangle.
    if ( activeFacet == kODNULL )
        return *partWindowBounds;

    // For the purposes of tiling, we need the to know the area of the
    // document the frame occupies. We do this by getting the bouding
    // box and offsetting it by the aggregate external window transform
    // of the facet.

    ODShape* frameShape = activeFacet->GetFrame(ev)->AcquireFrameShape(ev, kODNULL);
    TempODTransform windowFrameTransform = activeFacet->AcquireWindowFrameTransform(ev, kODNULL);
    TempODShape boundsShape = ODCopyAndRelease(ev, frameShape);

    // Translate the bounds rect into window coordinates.
    boundsShape->Transform(ev, windowFrameTransform);

    // Get and convert the bounding box into a QuickDraw rectangle.
    ODRect    bbox;
    Rect    bounds;
    boundsShape->GetBoundingBox(ev, &bbox);
    FixedToIntRect(bbox, bounds);

    // We then call our method to tile the child window.
    *partWindowBounds = TilePartWindow(ev, &bounds, partWindowBounds);

    // Set the port and origin so we can convert the rect to
    // global Window Mgr coordinates.
    SetPort(activeFacet->GetCanvas(ev)->GetQDPort(ev));
    SetOrigin(0,-kMacWindowTitleBarHeight);

    // Convert the local coordinates to global Window Mgr coordinates.
    LocalToGlobal((Point*)(&(partWindowBounds->top)));
    LocalToGlobal((Point*)(&(partWindowBounds->bottom)));

    return *partWindowBounds;
}

//------------------------------------------------------------------------------
// Method:        GetActiveFacetForFrame
// Origin:        Cappuccino
//
// Description:    This method is called by the part when it needs to know what the
//                current active facet is.
//
//                The part uses this method specifically to find the facet of a
//                source frame when opening a part window.
//------------------------------------------------------------------------------

ODFacet* Cappuccino::GetActiveFacetForFrame( Environment*    ev,
                                             ODFrame*        frame )
{
    SOM_Trace("Cappuccino","GetActiveFacetForFrame");

    ASSERT_NOT_NULL(frame);

    ODFacet*    facet = kODNULL;
    CFrameInfo*    frameInfo = CFrameInfo::GetFrameInfo(ev, frame);

    // If the frame is active, and it should be, get the active facet
    // from the frame state info.
    if ( frameInfo->IsFrameActive() )
    {
        facet = frameInfo->GetActiveFacet();
    }
    else
    // Otherwise, iterate over the display frames looking for one
    // that has an active facet... there should be at least one.
    {
        TempODFrameFacetIterator fiter(ev, frame);
        for ( ODFacet* selectedFacet = fiter.First(); fiter.IsNotComplete();
              selectedFacet = fiter.Next() )
        {
            if ( selectedFacet->IsSelected(ev) )
            {
                facet = selectedFacet;
                break;
            }
        }
    }

    // If there are no active facets anywhere, this method should never
    // have been called, so signal an error.
    if ( facet == kODNULL )
        THROW(kODErrInvalidFrame);

    return facet;
}

//------------------------------------------------------------------------------
// Method:        ContentUpdated
// Origin:        Cappuccino
//
// Description:    This method is called when the content has changed in order
//                to cause all of the frames belonging to this part to be told
//                that the content was updated.
//------------------------------------------------------------------------------

void Cappuccino::ContentUpdated( Environment*    ev )
{
    SOM_Trace("Cappuccino","ContentUpdated");

    ODUpdateID pasteUpdateID = fSession->UniqueUpdateID(ev);

    // Iterate over the frames we are displayed through and determine which
    // ones we need to invalidate.
    CListIterator fiter(fDisplayFrames);
    for ( CFrameProxy* proxy = (CFrameProxy*) fiter.First();
            fiter.IsNotComplete(); proxy = (CFrameProxy*) fiter.Next() )
    {
        // If the display frame is real (has been "connected" or was "added")
        // call ContentUpdated for the frame; otherwise, ignore it.
        if ( proxy->FrameIsLoaded(ev) )
        {
            proxy->GetFrame(ev)->ContentUpdated(ev, pasteUpdateID);
        }
    }
}

//------------------------------------------------------------------------------
// Method:        TryToEdit
// Origin:        Cappuccino
//
// Description:    This method is called when the content has changed in order
//                to cause all of the frames belonging to this part to be told
//                that the content was updated.
//------------------------------------------------------------------------------

ODBoolean Cappuccino::TryToEdit( Environment*        ev,
                                 ODFrame*            frame )
{
    SOM_Trace("Cappuccino","CanEdit");

    ASSERT_NOT_NULL(frame);

    ODBoolean canEdit = kODFalse;

    if ( frame->GetLinkStatus(ev) == kODInLinkDestination )
    {
        if ( frame->EditInLink(ev) )
        {
            if ( frame->GetLinkStatus(ev) != kODInLinkDestination )
                canEdit = kODTrue;
        }
        else
        {
            this->DoDialogBox(ev, frame, kErrorBoxID, kErrCantEditLinkDest);
        }
    }
    else
    {
        canEdit = kODTrue;
    }

    return canEdit;
}

//==============================================================================
#pragma mark    • Imaging •
//==============================================================================

//------------------------------------------------------------------------------
// Method:        Draw
// Origin:        ODPart
//
// Description:    This method is called when a facet of a part's display
//                frame intersects the invalidated portion of an OpenDoc
//                window. The invalidShape parameter passed in is the
//                portion of the facet which has been invalidated.
//
//                The part sets up the drawing environment using a
//                C++ helper class (CFocus) and then calls the
//                appropriate drawing method based on the frame's
//                viewType.
//------------------------------------------------------------------------------

void Cappuccino::Draw( Environment*        ev,
                       ODFacet*            facet,
                       ODShape*            invalidShape )
{
    SOM_Trace("Cappuccino","Draw");

    ASSERT_NOT_NULL(facet);

    // Focus the port and origin for drawing in our facet.
    // Note that this instance of the CFocusDrawingEnv class
    // is being allocated on the stack. When the execution
    // leaves the scope of this method, the destructor (which
    // cleans up the drawing environment) is automatically
    // called.
    CFocus initiateDrawing(ev, facet, invalidShape);

    ODTypeToken view = facet->GetFrame(ev)->GetViewType(ev);

    if ( view == gGlobals->fLargeIconView || view == gGlobals->fSmallIconView )
        this->DrawIconView(ev, facet);
    else if ( view == gGlobals->fThumbnailView )
        this->DrawThumbnailView(ev, facet);
    else
        this->DrawFrameView(ev, facet);
}

//------------------------------------------------------------------------------
// Method:        DrawFrameView
// Origin:        Cappuccino
//
// Description:    This method is called by the part when the frame being drawn is
//                in "frame" view.
//
//                Cappuccino really has not intrisic content. However, to provide
//                some visual display, we draw the class name at 80% of the
//                frame's current height using an bold font.
//------------------------------------------------------------------------------

void Cappuccino::DrawFrameView( Environment*    ev,
                                ODFacet*        facet )
{
    SOM_Trace("Cappuccino","DrawFrameView");

    fContent->Draw(ev, facet, fSettings);
}

//------------------------------------------------------------------------------
// Method:        DrawIconView
// Origin:        Cappuccino
//
// Description:    This method is called by the part when the frame being
//                drawn is in "standard icon" view.
//
//                The part uses the Icon Utilities toolbox manager to
//                aid in drawing icons in active windows. The Guidelines
//                require a different appearance for selected icons in
//                inactive windows, which we do manually.
//------------------------------------------------------------------------------

void Cappuccino::DrawIconView( Environment*        ev,
                               ODFacet*            facet )
{
    SOM_Trace("Cappuccino","DrawIconView");

    ASSERT_NOT_NULL(facet);

    ODFrame*    frame        = facet->GetFrame(ev);
    ODTypeToken    viewType    = frame->GetViewType(ev);
    CFrameInfo*    frameInfo     = CFrameInfo::GetFrameInfo(ev, frame);

    IconTransformType transformType = ttNone;

    // Check to see if the facet is selected
    if ( facet->GetHighlight(ev) == kODFullHighlight )
        transformType = ttSelected;

    // Check to see if the frame has been opened into a part window.
    TempODWindow window = frameInfo->AcquirePartWindow(ev);
    if ( window && window->IsShown(ev) )
        transformType |= ttOpen;

    // Draw the icon.
    Rect iconRect;
    if ( viewType == gGlobals->fLargeIconView )
        SetRect(&iconRect, 0, 0, kODLargeIconSize, kODLargeIconSize);
    else // ( viewType == gGlobals->fSmallIconView )
        SetRect(&iconRect, 0, 0, kODSmallIconSize, kODSmallIconSize);

    CUsingLibraryResources res;
    PlotIconID(&iconRect, atAbsoluteCenter, transformType, kBaseResourceID);
}

//------------------------------------------------------------------------------
// Method:        DrawThumbnailView
// Origin:        Cappuccino
//
// Description:    This method is called by the part when the frame being
//                drawn is in "thumbnail" view.
//
//                The part uses a picture for its thumbnail view because
//                it has no intrinsic content. A picture resource is
//                probably not sufficient for parts with real content.
//------------------------------------------------------------------------------

void Cappuccino::DrawThumbnailView( Environment*    ev,
                                    ODFacet*        facet )
{
    SOM_Trace("Cappuccino","DrawThumbnailView");

    ASSERT_NOT_NULL(facet);

    // Create or retrieve a cached thumbnail picture.
    PicHandle thumbnail = this->GenerateThumbnail(ev, facet->GetFrame(ev));

    Rect bounds = (**thumbnail).picFrame;
    DrawPicture(thumbnail, &bounds);
}

//------------------------------------------------------------------------------
// Method:        GeometryChanged
// Origin:        ODPart
//
// Description:    This method is called when the ExternalTransform or
//                ClipShape of a facet on one this part's display frames
//                changes.
//------------------------------------------------------------------------------

void Cappuccino::GeometryChanged( Environment*    ev,
                                  ODFacet*        facet,
                                  ODBoolean        clipShapeChanged,
                                  ODBoolean        externalTransformChanged )
{
    SOM_Trace("Cappuccino","GeometryChanged");

    ASSERT_NOT_NULL(facet);

    if ( clipShapeChanged )
        // Specifying kODNULL means to invalidate the clipShape (which was
        // calculated from the usedShape).
        facet->Invalidate(ev, kODNULL, kODNULL);
}

//------------------------------------------------------------------------------
// Method:        HighlightChanged
// Origin:        ODPart
//
// Description:    This method is called when a facet....
//------------------------------------------------------------------------------

void Cappuccino::HighlightChanged(Environment* ev, ODFacet* facet)
{
    SOM_Trace("Cappuccino","HighlightChanged");

    ASSERT_NOT_NULL(facet);

    ODFrame* frame = facet->GetFrame(ev);

    // The frame view has no "special" drawing characteristics
    // when opened or selected, so we don't need to update our
    // content.
    if ( frame->GetViewType(ev) != gGlobals->fFrameView )
        frame->Invalidate(ev, kODNULL, kODNULL);
}

//------------------------------------------------------------------------------
// Method:        CanvasChanged
// Origin:        ODPart
//
// Description:    This method is called when a facet's canvas ...
//------------------------------------------------------------------------------

void Cappuccino::CanvasChanged( Environment*    ev,
                                ODFacet*        facet)
{
    SOM_Trace("Cappuccino","CanvasChanged");

}

//------------------------------------------------------------------------------
// Method:        CanvasUpdated
// Origin:        ODPart
//
// Description:    This method is called when a canvas ...
//------------------------------------------------------------------------------

void Cappuccino::CanvasUpdated( Environment*    ev,
                                ODCanvas*        canvas)
{
    SOM_Trace("Cappuccino","CanvasUpdated");

}

//------------------------------------------------------------------------------
// Method:        GetPrintResolution
// Origin:        ODPart
//
// Description:    This method is called when the minimum print resolution
//                supported by this part is needed.
//------------------------------------------------------------------------------

ODULong Cappuccino::GetPrintResolution( Environment*    ev,
                                        ODFrame*        frame)
{
    SOM_Trace("Cappuccino","GetPrintResolution");

    return kMinImagingResolution;
}

//------------------------------------------------------------------------------
// Method:        FacetAdded
// Origin:        ODPart
//
// Description:    This method is called when any part adds a facet to
//                one of our display frames.
//
//                The part calls ViewTypeChanged to load the appropriate
//                resource for display in this facet and then activates
//                the frame if we are the root part of an active window.
//------------------------------------------------------------------------------

void Cappuccino::FacetAdded( Environment*    ev,
                             ODFacet*        facet )
{
    SOM_Trace("Cappuccino","FacetAdded");

    ASSERT_NOT_NULL(facet);

    ODFrame* frame = facet->GetFrame(ev);
    CFrameInfo* frameInfo = CFrameInfo::GetFrameInfo(ev, frame);

    // If a root facet is being added, the frame should be activated when the
    // window is "selected". This prevents OpenDoc from getting into an
    // ambiguous state of no part having the selection focus.

    if ( frame->IsRoot(ev) )
    {
        frameInfo->SetActiveFacet(facet);
        frameInfo->SetFrameReactivate(kODTrue);
    }

    // If a frame had all of its facets removed, the frame would have
    // hidden any of its part windows. If the frame becomes visible again,
    // by having a facet added to it, we will "show" the part window for
    // the frame.

    if ( CountFacets(ev, frame) == 1 )
    {
        TempODWindow window = frameInfo->AcquirePartWindow(ev);
        if ( window )
            window->Show(ev);
    }
}

//------------------------------------------------------------------------------
// Method:        FacetRemoved
// Origin:        ODPart
//
// Description:    This method is called when any part removes a facet
//                from one of our display frames.
//
//                The part just removes the "active" note from the
//                appropriate display frame if necessary since this
//                facet will not be available, nor active, again.
//------------------------------------------------------------------------------

void Cappuccino::FacetRemoved( Environment*    ev,
                               ODFacet*        facet )
{
    SOM_Trace("Cappuccino","FacetRemoved");

    ASSERT_NOT_NULL(facet);

    ODFrame*    frame           = facet->GetFrame(ev);
    TempODFrame    containingFrame = frame->AcquireContainingFrame(ev);
    CFrameInfo* frameInfo       = CFrameInfo::GetFrameInfo(ev, frame);

    // If the facet was the active facet, it can no longer be.
       if ( ODObjectsAreEqual(ev, frameInfo->GetActiveFacet(), facet) )
        frameInfo->SetActiveFacet(kODNULL);

    // If a frame has all of its facets removed and its containing frame set
    // to NULL, the frame becomes "hidden". If the frame owns a part window,
    // the part window should also be hidden.

    if ( CountFacets(ev, frame) == 0 && containingFrame == kODNULL )
    {
        TempODWindow window = frameInfo->AcquirePartWindow(ev);
        if ( window )
            window->Hide(ev);
    }
}

//------------------------------------------------------------------------------
// Method:        InvalidateFrameViews
// Origin:        Cappuccino
//
// Description:    This method is called when the content has changed in order
//                to cause all of the frames belonging to this part that are
//                in frame view to be redrawn with the new content.
//------------------------------------------------------------------------------

void Cappuccino::InvalidateFrameViews( Environment*        ev,
                                       ODShape*            invalidShape,
                                       ODCanvas*        biasCanvas )
{
    // Iterate over the frames we are displayed through and determine which
    // ones we need to invalidate.
    CListIterator fiter(fDisplayFrames);
    for ( CFrameProxy* proxy = (CFrameProxy*) fiter.First();
            fiter.IsNotComplete(); proxy = (CFrameProxy*) fiter.Next() )
    {
        // If the display frame is real (has been "connected" or was "added")
        // get its view type; otherwise, ignore it.
        if ( proxy->FrameIsLoaded(ev) )
        {
            ODFrame* frame = proxy->GetFrame(ev);

            if ( frame->GetViewType(ev) == gGlobals->fFrameView )
                frame->Invalidate(ev, kODNULL, kODNULL);
        }
    }
}

//==============================================================================
#pragma mark    • Activation •
//==============================================================================

//------------------------------------------------------------------------------
// Method:        BeginRelinquishFocus
// Origin:        ODPart
//
// Description:    This method is called when another part (or possibly
//                ourself) is requesting a focus for one of its display
//                frames. Returning true means we are willing to give
//                up the requested focus.
//
//                The part willingly gives up any focus unless it is the
//                modal focus which we don't want to give up until we
//                are completely done displaying a modal dialog.
//------------------------------------------------------------------------------

ODBoolean Cappuccino::BeginRelinquishFocus( Environment*    ev,
                                            ODTypeToken        focus,
                                            ODFrame*        ownerFrame,
                                            ODFrame*        proposedFrame )
{
    SOM_Trace("Cappuccino","BeginRelinquishFocus");

    ODBoolean willRelinquish = kODTrue;

    // Another part is trying to put up a Modal dialog while we
    // are currently displaying ours. Deny the request.
    if ( focus == gGlobals->fModalFocus )
    {
        TempODPart proposedPart = ODAcquirePart(ev, proposedFrame);
        if ( ODObjectsAreEqual(ev, proposedPart, fSelf) == kODFalse )
            willRelinquish = kODFalse;
    }

    return willRelinquish;
}

//------------------------------------------------------------------------------
// Method:        CommitRelinquishFocus
// Origin:        ODPart
//
// Description:    This method is called when it is actually time to give
//                up a focus that had been requested by another part (or
//                possibly ourself).
//
//                The part calls its FocusLost method to handle the
//                "reliquishing" of the particular focus.
//------------------------------------------------------------------------------

void Cappuccino::CommitRelinquishFocus( Environment*    ev,
                                        ODTypeToken        focus,
                                        ODFrame*        ownerFrame,
                                        ODFrame*        proposedFrame )
{
    SOM_Trace("Cappuccino","CommitRelinquishFocus");

    // We agreed to give up our FocusSet and now we are being asked to
    // do so.
    if ( focus == gGlobals->fSelectionFocus )
    {
        fSession->GetArbitrator(ev)->RelinquishFocusSet(ev, gGlobals->fUIFocusSet, ownerFrame);
        this->PartDeactivated(ev, ownerFrame);
    }
}

//------------------------------------------------------------------------------
// Method:        AbortRelinquishFocus
// Origin:        ODPart
//
// Description:    This method is called when another part (or possibly
//                ourself) requested a focus for one of its display
//                frames, but we returned kODFalse from
//                BeginRelinqishFocus for one, or all, of the requested
//                focus. At this point, we are being told to resume
//                ownership of the focus.
//------------------------------------------------------------------------------

void Cappuccino::AbortRelinquishFocus( Environment*        ev,
                                       ODTypeToken        focus,
                                       ODFrame*            ownerFrame,
                                       ODFrame*            proposedFrame )
{
    SOM_Trace("Cappuccino","AbortRelinquishFocus");

    // Some parts may have suspended some events in the BeginRelinquishFocus
    // method. If so, they would resume those events here.
}

//------------------------------------------------------------------------------
// Method:        FocusAcquired
// Origin:        ODPart
//
// Description:    This method is called when the Arbitrator has
//                registered us as the "owner" of the particular focus.
//                This can occur if we are explicitly assigned a focus, or if a
//                focus is transfered to one of the part's display frames.
//
//                The part will request its complete focus set to become "active".
//                If the part is successful, we notify ourself to become active.
//------------------------------------------------------------------------------

void Cappuccino::FocusAcquired( Environment*    ev,
                                ODTypeToken        focus,
                                ODFrame*        ownerFrame )
{
    SOM_Trace("Cappuccino","FocusAcquired");

    ODArbitrator* arbitrator =  fSession->GetArbitrator(ev);

    if ( gGlobals->fUIFocusSet->Contains(ev, focus) )
    {
        if ( arbitrator->RequestFocusSet(ev, gGlobals->fUIFocusSet, ownerFrame) )
            this->PartActivated(ev, ownerFrame);
    }
}

//------------------------------------------------------------------------------
// Method:        FocusLost
// Origin:        ODPart
//
// Description:    This method is called when the Arbitrator has
//                unregistered us as the "owner" of the particular
//                focus.
//
//                The part unmarks the active frame if the selection
//                focus is lost.
//------------------------------------------------------------------------------

void Cappuccino::FocusLost( Environment*    ev,
                            ODTypeToken        focus,
                            ODFrame*        ownerFrame )
{
    SOM_Trace("Cappuccino","FocusLost");

    if ( gGlobals->fUIFocusSet->Contains(ev, focus) )
    {
        fSession->GetArbitrator(ev)
                ->RelinquishFocusSet(ev, gGlobals->fUIFocusSet, ownerFrame);

        this->PartDeactivated(ev, ownerFrame);
    }
}

//------------------------------------------------------------------------------
// Method:        RelinquishAllFoci
// Origin:        Cappuccino
//
// Description:    This method is called when a frame is going away. The method
//                relinquishes all foci the frame owns.
//------------------------------------------------------------------------------

void Cappuccino::RelinquishAllFoci( Environment*    ev,
                                    ODFrame*        frame )
{
    SOM_Trace("Cappuccino","RelinquishAllFoci");

    if ( HasAnyFocusInSet(ev, frame, gGlobals->fUIFocusSet) )
    {
        fSession->GetArbitrator(ev)->RelinquishFocusSet(ev, gGlobals->fUIFocusSet, frame);
        this->PartDeactivated(ev, frame);
    }

    // We also need to relinquish any other foci that we might have in this
    // routine.  In order to do this, call the Arbitrator's AcquireFocusOwner
    // function, and if it is this frame, call RelinquishFocus for that focus
    // type and do whatever we need to do when we are giving up that focus.
}

//------------------------------------------------------------------------------
// Method:        PartActivated
// Origin:        Cappuccino
//
// Description:    This method is called when the part has successfully acquired
//                the set of foci which allow it to "run".
//------------------------------------------------------------------------------

void Cappuccino::PartActivated( Environment*    ev,
                                ODFrame*        frame )
{
    SOM_Trace("Cappuccino","PartActivated");

    // We are required to re-validate the menubar before displaying it because
    // any part can/could swap the base menubar at any time.
    if ( !gGlobals->fMenuBar->IsValid(ev) )
        this->BuildMenuBar(ev);

    // Display our menu bar.
    gGlobals->fMenuBar->Display(ev);

    // And set our "active" state.
    CFrameInfo* frameInfo = CFrameInfo::GetFrameInfo(ev, frame);
    frameInfo->SetFrameActive(kODTrue);
}

//------------------------------------------------------------------------------
// Method:        PartDeactivated
// Origin:        Cappuccino
//
// Description:    This method is called when the part has been asked to
//                relinquish the foci from its UI focus set.
//------------------------------------------------------------------------------

void Cappuccino::PartDeactivated( Environment*        ev,
                                  ODFrame*            frame )
{
    SOM_Trace("Cappuccino","PartDeactivated");

    // And set our "active" state.
    CFrameInfo* frameInfo = CFrameInfo::GetFrameInfo(ev, frame);
    frameInfo->SetFrameActive(kODFalse);
}

//------------------------------------------------------------------------------
// Method:        ActivateFrame
// Origin:        Cappuccino
//
// Description:    This method is called by the part when a kODEvtMouseUp
//                occurs in an inactive frame in an active window, and
//                when an OpenDoc document comes forward.
//
//                The part activates the frame by requesting the
//                UIFocusSet (created in Initialize) and by calling
//                FocusAcquired if we were successful. The method
//                returns true if no problems were encountered as a
//                signal to the caller that the frame is now "active".
//------------------------------------------------------------------------------

ODBoolean Cappuccino::ActivateFrame( Environment*    ev,
                                     ODFrame*        frame )
{
    SOM_Trace("Cappuccino","ActivateFrame");

    ODBoolean activated = kODFalse;

    // Request the set of foci necessary to become active.
    if ( fSession->GetArbitrator(ev)
            ->RequestFocusSet(ev, gGlobals->fUIFocusSet, frame) )
    {
        // Activate the part.
        this->PartActivated(ev, frame);
        // We were able to become active.
        activated = kODTrue;
    }

    // Let our caller know we succeded or failed.
    return activated;
}

//------------------------------------------------------------------------------
// Method:        WindowActivating
// Origin:        Cappuccino
//
// Description:    This method is called by the part when a window activation
//                event (kODEvtActivate) occurs.
//
//                The part remembers the frame's active state and restores it when
//                events come in. If the frame is active and the window is being
//                sent into the background, remember to reactivate the part when
//                the window is reactivated.
//------------------------------------------------------------------------------

void Cappuccino::WindowActivating( Environment*        ev,
                                   ODFrame*            frame,
                                   ODBoolean        activating )
{
    SOM_Trace("Cappuccino","WindowActivating");

    ASSERT_NOT_NULL(frame);

    CFrameInfo* frameInfo = CFrameInfo::GetFrameInfo(ev, frame);

    // The window is being activated and we had the selection focus when
    // the window was deactivated, so activate ourself.
    if ( activating && frameInfo->FrameNeedsReactivating() )
    {
        this->ActivateFrame(ev, frame);
        frameInfo->SetFrameReactivate(kODFalse);
    }
    // The window is being deactivated and we are the active part.
    // Give up our foci and remind ourselves that we need to request
    // the focus when the window is reactivated.
    else if ( !activating && frameInfo->IsFrameActive() )
    {
        frameInfo->SetFrameReactivate(kODTrue);
    }
}

//==============================================================================
#pragma mark    • Event Handling •
//==============================================================================

//------------------------------------------------------------------------------
// Method:        HandleEvent
// Origin:        ODPart
//
// Description:    The method is called when an event, which falls into
//                the category of an owned focus, occurs. The two
//                exceptions to this are "mouse movement" events and
//                embedded frame events, which can occur when a part
//                owns no foci.
//
//                The part returns true if the event was handled.
//------------------------------------------------------------------------------


ODBoolean Cappuccino::HandleEvent( Environment*        ev,
                                   ODEventData*        event,
                                   ODFrame*            frame,
                                   ODFacet*            facet,
                                   ODEventInfo*        eventInfo )
{
    SOM_Trace("Cappuccino","HandleEvent");

    ODBoolean    eventHandled = kODFalse;

    // Event handling is basically the same as standard Macintosh applications,
    // except that the events have been renamed for cross-platform compatability.

    switch ( event->what )
    {
        case kODEvtMouseDown:
        case kODEvtMouseUp:
            eventHandled = this->HandleMouseEvent(ev, event, facet, eventInfo);
            break;

        case kODEvtMenu:
            eventHandled = this->HandleMenuEvent(ev, event, frame);
            break;

        case kODEvtActivate:
            // We are being notified that a window we are displayed in has
            // just been de/activated (un/hilighted).
            this->WindowActivating(ev, frame, (event->modifiers & activeFlag));
            eventHandled = kODTrue;
            break;

        case kODEvtMouseEnter:
        case kODEvtMouseLeave:
            SetCursor(&ODQDGlobals.arrow);
            eventHandled = kODTrue;
            break;

        case kODEvtMouseWithin:
            eventHandled = kODTrue;
            break;

        // Other events a part might handle
        case kODEvtNull:
        case kODEvtMouseDownEmbedded:
        case kODEvtMouseUpEmbedded:
        case kODEvtMouseDownBorder:
        case kODEvtMouseUpBorder:
        case kODEvtWindow:
        case kODEvtKeyDown:
        case kODEvtKeyUp:
        case kODEvtAutoKey:
        case kODEvtOS:
        case kODEvtDisk:

        default:
            break;
    }

    return eventHandled;
}

//------------------------------------------------------------------------------
// Method:        BuildMenuBar
// Origin:        Cappuccino
//
// Description:    This method is called when the menubar needs to be created or
//                changed (because it has become invalid).
//------------------------------------------------------------------------------

void Cappuccino::BuildMenuBar( Environment* ev )
{
    if (gGlobals->fMenuBar == kODNULL || !gGlobals->fMenuBar->IsValid(ev))
    {
        ODBoolean changingBaseMenuBar = (gGlobals->fMenuBar != kODNULL);

        if (changingBaseMenuBar)
        {
            // Remove our menus from the old menubar.
            for (ODSShort index = 0; index < kNumMenus; index++)
            {
                ODSShort id = kBaseMenuID + index;
                gGlobals->fMenuBar->RemoveMenu(ev, id);
            }
        }

        ODReleaseObject(ev, gGlobals->fMenuBar);

        // It is required that parts instantiate their menu bars from
        // the base OpenDoc menu bar. This maintains consistency in the
        // default menu items and their placement.
        // Since the object is a copy, we can add and subtract menus and
        // items without affecting other running parts.
        gGlobals->fMenuBar = fSession->GetWindowState(ev)->CopyBaseMenuBar(ev);

        // Add our resource-based menus and register all the editor specific
        // command numbers.
        CUsingLibraryResources res;
        for (ODSShort index = 0; index < kNumMenus; index++)
        {
            ODSShort id = kBaseMenuID + index;

            MenuHandle menu = GetMenu(id);
            if (menu != kODNULL)
                gGlobals->fMenuBar->AddMenuLast(ev, id, menu, fSelf);
        }

        // Register commands for our menu items.
        gGlobals->fMenuBar->RegisterCommand(ev, kCommandSpeak,    kMiscMenuID, 1);
#ifndef qViewerBuild
        gGlobals->fMenuBar->RegisterCommand(ev, kCommandSetText,  kMiscMenuID, 3);
        gGlobals->fMenuBar->RegisterCommand(ev, kCommandSettings, kMiscMenuID, 4);
#endif
    }
}

//------------------------------------------------------------------------------
// Method:        AdjustMenus
// Origin:        ODPart
//
// Description:    This method is called when a kODEvtMouseDown event occurs in the
//                menubar and the part owns the "menu" focus, or when the part is
//                root part of a document.
//
//                The part first verifies that the base menubar has not been
//                modified, then enables the menu items and changes their names
//                where appropriate (eg. About Cappuccino...).
//------------------------------------------------------------------------------

void Cappuccino::AdjustMenus( Environment*    ev,
                              ODFrame*        frame )
{
    SOM_Trace("Cappuccino","AdjustMenus");

    // The menubar object always calls the root part's AdjustMenus method before
    // calling the menu focus owner's. Because of this, we need to validate the
    // menubar in the case where we are the root part.
    if ( frame->IsRoot(ev) )
    {
        // We are required to re-validate the menubar before displaying it because
        // any part can/could swap the base menubar at any time.
        if ( !gGlobals->fMenuBar->IsValid(ev) )
            this->BuildMenuBar(ev);

         // PRINTING: Always enable Page Setup and Print when the root part.
         // Note: We call AcquireCurrentMenuBar here because, if we support
         // embedding, we have to enable the print menus whenever we are the
         // root part of the window, whether or not we have the menu focus.
        TempODMenuBar mbar = fSession->GetWindowState(ev)->AcquireCurrentMenuBar(ev);
        mbar->EnableCommand(ev, kODCommandPageSetup, kODTrue);
        mbar->EnableCommand(ev, kODCommandPrint, kODTrue);
    }

    // -- Cappuccino menu items --

#ifndef qViewerBuild
    gGlobals->fMenuBar->EnableCommand(ev, kCommandSettings, !fReadOnlyStorage);
    gGlobals->fMenuBar->EnableCommand(ev, kCommandSetText,  !fReadOnlyStorage);
#endif

    gGlobals->fMenuBar->EnableCommand(ev, kCommandSpeak, HasSpeech() &&
                                                !fContent->IsEmpty());

    // -- Standard menu items --

    // Enable the "View As Window" command always when we're not at the root.
    gGlobals->fMenuBar->EnableCommand(ev, kODCommandViewAsWin, !frame->IsRoot(ev));

    // Enable/disable the clipboard-related menu items
    this->AdjustClipboardComands(ev, frame);

    TRY
        ODArbitrator* arbitrator = fSession->GetArbitrator(ev);
        TempODFrame menuOwner = arbitrator->AcquireFocusOwner(ev, gGlobals->fMenuFocus);

        // There is no need to load a resource, create an ODIText object, set the menubar,
        // and cleanup, if we don't own the menu focus.
        if ( ODObjectsAreEqual(ev, frame, menuOwner) )
        {
            Str63 text;

            // Get the "about" string from our library's resources.
            // (note: ODGetIndString focuses the resource fork for us)
            ODGetIndString(text, kMenuStringResID, kAboutTextID);
            // Create an IText object to pass into the menubar.
            TempODIText    menuItem = CreateIText(gGlobals->fEditorsScript,
                                               gGlobals->fEditorsLanguage,
                                               (StringPtr) &text);
            // Change the "About" menu item text for our part.
            gGlobals->fMenuBar->SetItemString(ev, kODCommandAbout, menuItem);
        }
    CATCH_ALL
        // consume exception
    ENDTRY
}

//------------------------------------------------------------------------------
// Method:        HandleMenuEvent
// Origin:        Cappuccino
//
// Description:    This method is called by the part when a menu event is
//                received.
//
//                Using the menu bar object, we determine what the menu
//                command is, and call the appropriate method to handle
//                it.
//------------------------------------------------------------------------------

ODBoolean Cappuccino::HandleMenuEvent( Environment*        ev,
                                       ODEventData*        event,
                                       ODFrame*            frame )
{
    SOM_Trace("Cappuccino","HandleMenuEvent");

    ODULong        menuResult    = event->message;
    ODUShort    menu        = HiWord(menuResult);
    ODUShort    item        = LoWord(menuResult);

    switch ( gGlobals->fMenuBar->GetCommand(ev, menu, item) )
    {
        // -- Cappuccino menu items --

#ifdef powerc
        case kCommandSpeak:
            if ( HasSpeech() )
            {
                if ( SpeakString(fContent->GetString()) != noErr )
                {
                    this->DoDialogBox(ev, frame, kErrorBoxID,
                                      kErrSpeechManagerProblem);
                }
            }
            break;
#endif

#ifndef qViewerBuild
        case kCommandSettings:
            this->ShowSettingsDialog(ev, frame);
            break;

        case kCommandSetText:
            this->ShowSetTextDialog(ev, frame);
            break;
#endif

        // -- Standard menu items --

        case kODCommandAbout:
            this->DoDialogBox(ev, frame, kAboutBoxID);
            break;

        case kODCommandPageSetup:
            // If the user modified page setup, the print
            // job needs to be saved. We don't call our
            // internal SetDirty() method because the change
            // doesn't affect content.
            if ( fPrinter && fPrinter->PageSetup(ev) )
                ODGetDraft(ev, fSelf)->SetChangedFromPrev(ev);
            break;

        case kODCommandPrint:
            if ( fPrinter )
                fPrinter->PrintDocument(ev, frame);
            break;

        case kODCommandCut:
            this->DoCut(ev, frame);
            break;

        case kODCommandCopy:
            this->DoCopy(ev, frame);
            break;

        case kODCommandPaste:
            this->DoPaste(ev, frame);
            break;

        case kODCommandPasteAs:
            this->DoPasteAs(ev, frame);
            break;

        case kODCommandClear:
            this->DoClear(ev, frame);
            break;

        case kODCommandViewAsWin:
            this->Open(ev, frame);
            break;

        // Other commands a part might handle
        case kODCommandOpen:
        case kODCommandInsert:
        case kODCommandSelectAll:
        case kODCommandGetPartInfo:
        case kODCommandPreferences:

        default:
            return kODFalse;
    }

    return kODTrue;
}

//------------------------------------------------------------------------------
// Method:        HandleMouseEvent
// Origin:        Cappuccino
//
// Description:    This method is called by the part when a mouse event
//                is recieved.
//
//                A typical part would determine the event type(up/down)
//                and respond appropriately, but we have no "real"
//                content model, so we activate the part as appropriate
//                and call a generic method to handle the event.
//
// Remember:    When a frame is inactive, the first mouse up event
//                should activate it; inactive frames do not recieve
//                kODEvtMouseDown events.
//------------------------------------------------------------------------------

ODBoolean Cappuccino::HandleMouseEvent( Environment*    ev,
                                        ODEventData*    event,
                                        ODFacet*        facet,
                                        ODEventInfo*    eventInfo )
{
    SOM_Trace("Cappuccino","HandleMouseEvent");

    // If the facet parameter is invalid, the mouse up occurred outside the
    // bounds of a Modal window, otherwise it should be treated normally.

    if ( facet != kODNULL )
    {
        if ( event->what == kODEvtMouseUp )
        {
            ODWindow* window = facet->GetWindow(ev);

            TRY
                // Activate inactive windows on the first mouse up event.
                if ( !window->IsActive(ev) )
                    window->Select(ev);
                // Activate the frame (if needed) on all subsequent mouse up events.
                else
                {
                    ODFrame* frame = facet->GetFrame(ev);

                    // Get our state information from the PartInfo of the frame.
                    CFrameInfo* frameInfo = CFrameInfo::GetFrameInfo(ev, frame);

                    // If this frame is not the active one, activate it by requesting
                    // the appropriate foci.

                    if ( !frameInfo->IsFrameActive() )
                    {
                        if ( this->ActivateFrame(ev, frame) )
                            // Keep track of which facet was the last active for positioning
                            // child windows.
                            frameInfo->SetActiveFacet(facet);
                        else
                            // We were unable to acquire the necessary focus and activate it.
                            return kODFalse;
                    }
                }
            CATCH_ALL
            ENDTRY
        }
        else if ( event->what == kODEvtMouseDown )
        {
            this->DoMouseDown(ev, event, facet, eventInfo);
        }
    }
    else
    {
        // User clicked outside the bounds of a Modal window, though we actually
        // never display one.

        SysBeep(1);
    }

    return kODTrue;
}

//------------------------------------------------------------------------------
// Method:        DoMouseDown
// Origin:        Cappuccino
//
// Description:    This method is called by the part to handle mouse
//                events.
//------------------------------------------------------------------------------

void Cappuccino::DoMouseDown( Environment*        ev,
                              ODEventData*        event,
                              ODFacet*            facet,
                              ODEventInfo*        eventInfo )
{
    SOM_Trace("Cappuccino","DoMouseEvent");

    // If you part allows selections or a lasso tool, this is where you
    // would handle those events. This is also where you would handle
    // program controlled buttons or controls.

    // If the mouse was clicked on something that is draggable, then we
    // need to call WaitMouseMoved and possibly InitiateDrag.
    if ( WaitMouseMoved(event->where) )
    {
        (void) this->InitiateDrag(ev, event, facet, eventInfo->where);
    }
    else
    {
        Point where;

        // Get the localized mouse coordinates from the Event Info.
        where.h = FixedToInt(eventInfo->where.x);
        where.v = FixedToInt(eventInfo->where.y);

        // Handle the mouse down event.
    }
}

//------------------------------------------------------------------------------
// Method:        DoDialogBox
// Origin:        Cappuccino
//
// Description:    This method is called by the part when a dialog needs to be
//                displayed (eg. the About Box). If a valid error number is passed
//                in, an error dialog will be displayed.
//------------------------------------------------------------------------------

void Cappuccino::DoDialogBox( Environment*    ev,
                              ODFrame*        frame,
                              ODSShort        dialogID,
                              ODUShort        errorNumber )
{
    SOM_Trace("Cappuccino","DoDialogBox");

    ODFrame* focusFrame = frame;

    // If the calling method does not have a frame available to it, we need to
    // locate a frame to use for requesting the modal focus. Find the first valid
    // frame in our display frames list.
    if ( focusFrame == kODNULL )
    {
        CListIterator fiter(fDisplayFrames);
        for ( CFrameProxy* proxy = (CFrameProxy*) fiter.First();
                fiter.IsNotComplete(); proxy = (CFrameProxy*) fiter.Next() )
        {
            if ( proxy->FrameIsLoaded(ev) )
                focusFrame = proxy->GetFrame(ev);
            if ( focusFrame ) break;
        }
    }

    // Our dialog boxes are modal so we must request the Modal focus to prevent
    // multiple modal dialogs being displayed simultaneously.

    TempFocus modalFocus(ev, gGlobals->fModalFocus, focusFrame);
    if ( modalFocus.Request() )
    {
        ODSShort itemHit;

        // Dim the frontmost document window.
        fSession->GetWindowState(ev)->DeactivateFrontWindows(ev);

        CUsingLibraryResources res;

        DialogPtr dialog = GetNewDialog(dialogID, kODNULL, (WindowPtr) -1L);
        if ( dialog )
        {
            if ( errorNumber > 0 )
            {
                Handle    itemHandle;
                Rect    itemRect;
                short    itemType;
                Str255    errStr;

                GetIndString(errStr, kErrorStringResID, errorNumber);
                GetDialogItem(dialog, kErrStrFieldItem, &itemType, &itemHandle, &itemRect);
                SetDialogItemText(itemHandle, errStr);

                // We don't need the cancel button for an error dialog.
                HideDialogItem(dialog, cancel);

                SetDialogDefaultItem(dialog, ok);
            }

            SetCursor(&ODQDGlobals.arrow);
            ShowWindow(dialog);
            ModalDialog(kODNULL, &itemHit);
            DisposeDialog(dialog);
        }
        else
        {
            // Could not load About box dialog... something is amiss.
            SysBeep(2);
        }

        // Hilite the frontmost document window.
        fSession->GetWindowState(ev)->ActivateFrontWindows(ev);
    }
    else
    {
        // If we can't get the modal focus, then another modal dialog is
        // already being displayed.
        SysBeep(2);
    }
}

//------------------------------------------------------------------------------
// Method:        ShowSetTextDialog
// Origin:        Cappuccino
//
// Description:    The method is called by the part when the user chooses the
//                Set Text menu item.
//------------------------------------------------------------------------------

void Cappuccino::ShowSettingsDialog( Environment*    ev,
                                     ODFrame*        frame )
{
    SOM_Trace("Cappuccino","ShowSettingsDialog");

    CSettings::DoSettingsDialog(ev, frame, this, fSettings);
}

//------------------------------------------------------------------------------
// Method:        ShowSetTextDialog
// Origin:        Cappuccino
//
// Description:    The method is called by the part when the user chooses the
//                Set Text menu item.
//------------------------------------------------------------------------------

void Cappuccino::ShowSetTextDialog( Environment*    ev,
                                    ODFrame*        frame )
{
    SOM_Trace("Cappuccino","ShowSetTextDialog");

    CCappuccinoContent::DoSetTextDialog(ev, frame, this, fContent);
}